Skip to main content
POST
/
authorize
Create Authorization Session
curl --request POST \
  --url https://api.uip.digital/v1/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "platform_abc123",
  "client_secret": "secret_xyz789",
  "scopes": [
    "identify:create",
    "sign:create"
  ]
}
'
{
  "session_id": "sess_auth_1a2b3c4d",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2025-01-11T12:35:00Z"
}
Create an authorization session for platform delegation. Platforms use this endpoint to request delegated access to a business’s UIP capabilities. The business owner scans the QR code with their UIP app to grant the platform specific scopes of access. Upon approval, the platform receives a delegation token (uip_at_ prefix) that can be used in place of an API key for the granted scopes.

​
Request

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key: Bearer YOUR_API_KEY
Content-TypeYesMust be application/json

​
Body Parameters

​
client_id
string
required
The platform’s client ID, issued during platform registration.
​
client_secret
string
required
The platform’s client secret, issued during platform registration.
​
scopes
array
required
Array of permission scopes to request from the business.Valid scopes:
  • identify:create — Create identify sessions on behalf of the business
  • sign:create — Create sign sessions on behalf of the business
  • messages:create — Send messages on behalf of the business
  • messages:read — Read message status on behalf of the business
  • audits:read — Query audit records on behalf of the business
  • business:read — Read business profile information
Example: ["identify:create", "sign:create"]

​
Response

​
Success Response (200 OK)

​
session_id
string
required
Unique identifier for this authorization session.
​
expires_at
string
required
ISO 8601 timestamp when the session expires.
​
qr_code
string
required
Base64-encoded PNG data URI of the QR code for the business owner to scan. The QR code encodes https://www.uip.id/{session_id}.

​
Example Request

curl -X POST https://api.uip.digital/v1/authorize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "platform_abc123",
    "client_secret": "secret_xyz789",
    "scopes": ["identify:create", "sign:create"]
  }'

​
Example Response

{
  "session_id": "sess_auth_1a2b3c4d",
  "expires_at": "2025-01-11T12:35:00Z",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

​
Authorization Flow

1

Platform Requests Authorization

Platform calls this endpoint with client credentials and requested scopes
2

Display QR Code

Platform displays the QR code to the business owner. On mobile, show an “Open UIP” button linking to https://www.uip.id/{session_id}
3

Business Owner Scans

Business owner scans QR code with their UIP app and reviews the requested scopes
4

Business Owner Approves

Business owner approves with biometric verification, granting the requested scopes
5

Platform Polls for Token

Platform polls POST /v1/authorize/:id/status with client credentials until status is completed. The completed response includes the delegation token.
6

Platform Uses Token

Platform uses the delegation token (uip_at_ prefix) as a Bearer token to make API calls on behalf of the business
Webhook notification: In addition to polling, UIP sends an authorize.completed webhook when the business owner approves. See Webhooks for details.
Rate limit: The authorize endpoint has a stricter rate limit of 100 requests per minute per API key (vs. 300/min for other endpoints).

​
Errors

Possible error codes for this endpoint:
  • auth/missing-api-key - No API key provided
  • auth/invalid-api-key - Invalid API key
  • auth/scope-not-allowed - One or more requested scopes are not valid
  • request/invalid-payload - Missing required fields or invalid format
  • rate-limit/exceeded - Rate limit exceeded (100/min for authorize)
  • internal/server-error - Failed to create authorization session

Authorizations

​
Authorization
string
header
required

Use your UIP API key as a bearer token

Body

application/json
​
client_id
string
required

The platform's client ID, issued during platform registration.

​
client_secret
string
required

The platform's client secret, issued during platform registration.

​
scopes
enum<string>[]
required

Array of permission scopes to request from the business.

Available options:
identify:create,
sign:create,
messages:create,
messages:read,
audits:read,
business:read

Response

200 - application/json

Authorization session created

​
session_id
string

Unique identifier for this session

​
qr_code
string

Base64-encoded PNG data URI of the QR code. The QR code encodes https://www.uip.id/{session_id}

​
expires_at
string<date-time>

ISO 8601 timestamp when the session expires