Skip to main content

Issue a pre-authorization

This guide walks you through issuing a single medication pre-authorization from zero — the same pattern applies to labs, imaging, and in-clinic procedures with only the product codes and product_type changing.

By the end you'll have a valid authorization_code you can hand to the beneficiary (usually as a QR the pharmacy scans).

Before you start​

  • A sandbox client_id + client_secret from Osigu onboarding.
  • A sponsor slug your provider is affiliated with (check listSponsors if in doubt).
  • A test beneficiary the sponsor recognises.
  • Familiarity with Authorizations — the concept page explains why the flow is shaped the way it is; this guide only shows how.

1. Get an access token​

  1. 1Call the SSO server
    curl -X POST https://sandbox.osigu.com/v1/oauth/token \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -d "grant_type=client_credentials"
  2. 2Cache the token for ~50 minutes

    Do not call /oauth/token per request — it's rate-limited to 10/min. See Obtaining tokens for a caching pattern.

export TOKEN="eyJhbGciOiJSUzI1NiIs..."
export SPONSOR="sponsor-sandbox"

2. Find the beneficiary​

Sponsors define the search form dynamically. Fetch it, then submit:

curl "https://sandbox.osigu.com/v1/sponsors/$SPONSOR/forms" \
  -H "Authorization: Bearer $TOKEN"

Response shows the fields to fill in (typically document_type + document_number, or member_id). Now search:

curl -X POST "https://sandbox.osigu.com/v1/sponsors/$SPONSOR/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document_type":"CC","document_number":"1000000001"}'

Persist the beneficiary_id returned in the response.

3. Read the sponsor's configuration​

Before you build the request body, know what this sponsor demands:

curl "https://sandbox.osigu.com/arc/v1/sponsors/$SPONSOR/configuration?product_type=MEDICATION" \
  -H "Authorization: Bearer $TOKEN"

The response tells you which fields are required (e.g. professional_license_number, service_type_code), which authorization_type values are accepted, and whether OTP or biometric verification is needed downstream. Cache this response with a short TTL (5–15 min).

4. Initiate the authorization request​

curl -X POST "https://sandbox.osigu.com/arc/v1/authorization-requests" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_id": "bnf_01HW8GQ2KMNP3F4R5T6Y7U8I9O",
    "sponsor_slug": "sponsor-sandbox",
    "diagnosis_code": "R51",
    "products": [{
      "product_code": "MED-042",
      "product_type": "MEDICATION",
      "quantity": 30,
      "posology": "1 tablet every 8h for 10 days"
    }]
  }'

Response (202):

{
  "authorization_request_id": "areq_01HX9KP7VQ2D4FZ8N0YPRQAW6X",
  "status": "PENDING_INDICATION"
}

5. Attach the medical indication​

Most sponsors need a signed prescription or referral before they'll process the request. Two ways:

Multipart:

curl -X POST "https://sandbox.osigu.com/arc/v1/authorization-requests/areq_.../upload/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./indication.pdf" \
  -F "file_type=MEDICAL_INDICATION"

Base64 (if your caller can't do multipart): use attachAuthorizationIndicationBase64 with { "file_base64": "...", "file_type": "MEDICAL_INDICATION" }.

Not sure which file_type the sponsor wants? Call getAuthorizationDocumentPolicy — it returns the accepted types.

6. Complete the request​

curl -X POST "https://sandbox.osigu.com/arc/v1/authorization-requests/areq_.../complete" \
  -H "Authorization: Bearer $TOKEN"

If the sponsor evaluates synchronously, you get the authorization(s) in the response:

{
  "authorization_request_id": "areq_...",
  "status": "COMPLETED",
  "authorizations": [{
    "authorization_code": "AUTH-2026-001234",
    "product_type": "MEDICATION",
    "status": "APPROVED",
    "expires_at": "2026-07-25T00:00:00Z"
  }]
}

If the sponsor evaluates async, status is PENDING_SPONSOR and the outcome arrives via webhook — authorization.created for approvals, authorization.rejected for denials.

7. Hand the code to the beneficiary​

The authorization_code is what the pharmacy will scan (or type) at dispensation time. Rendering choices are yours — QR, barcode, plain number.

Troubleshooting​

SymptomFix
403 on step 2Provider not affiliated with sponsor. Check listSponsors.
422 on step 4 with error_code: 071-104Product not in your provider-products list. Register it first.
422 on step 4 with a missing-field errorCheck the sponsor configuration from step 3 — the sponsor requires a field you didn't send.
Step 6 returns PENDING_INDICATIONThe indication wasn't attached, or wasn't the file_type the sponsor expects.
Authorization returned REJECTEDSponsor denied it. Surface rejection_reason to the user.

Still stuck? Email support@osigu.com with your authorization_request_id.