Skip to main content

​
What is Platform Delegation?

Platform delegation allows third-party platforms to make UIP API calls on behalf of businesses. Instead of each business integrating UIP directly, a platform can handle the integration once and serve multiple businesses.
Example: A payroll platform can collect employee signatures for contracts on behalf of its business customers, without each business needing their own UIP integration.

​
How It Works

1

Platform Requests Authorization

The platform calls POST /v1/authorize with its client credentials and the scopes it needs
2

Business Owner Reviews

A QR code is displayed. The business owner scans it with their UIP app and reviews the requested permissions.
3

Business Approves

The business owner approves with biometric verification, granting the platform specific scopes
4

Platform Polls for Token

The platform polls POST /v1/authorize/:id/status with client credentials until status is completed. The completed response includes the delegation token (uip_at_ prefix).
5

Platform Makes API Calls

The platform uses the delegation token as a Bearer token to make API calls on behalf of the business

​
Available Scopes

Delegation tokens are scoped — they can only access APIs that the business explicitly granted:
ScopePermissionAPI Access
identify:createCreate identify sessionsPOST /v1/identify
sign:createCreate sign sessionsPOST /v1/sign
messages:createSend messagesPOST /v1/message
messages:readRead message statusMessage-related GET endpoints
audits:readQuery audit recordsGET /v1/audit/:id
business:readRead business infoBusiness profile endpoints
Principle of least privilege: Only request the scopes your platform actually needs. Businesses are more likely to approve minimal scope requests.

​
Using Delegation Tokens

Once you have a delegation token, use it exactly like an API key in the Authorization header: 
curl -X POST https://api.uip.digital/v1/identify \
  -H "Authorization: Bearer uip_at_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Verify employee identity",
    "requested_data": ["first_name", "last_name"]
  }'
Billing: API usage via delegation tokens is billed to the business that granted the delegation, not to the platform.

​
Authorization Flow Details

​
Creating an Authorization Session

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

​
Polling Authorization Status

curl -X POST "https://api.uip.digital/v1/authorize/sess_auth_1a2b3c4d/status" \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "platform_abc123",
    "client_secret": "secret_xyz789"
  }'
Why POST for status? The authorize status endpoint uses POST (not GET) because client credentials must be verified on every status check.

​
Completed Response

When the business owner approves, the status response includes the delegation token: 
{
  "status": "completed",
  "expires_at": "2025-01-11T12:35:00Z",
  "access_token": "uip_at_abc123xyz789..."
}

​
Webhook Notification

In addition to polling, UIP sends an authorize.completed webhook when the business owner approves. You can also receive delegation.revoked webhooks when a business revokes your access.

​
Scope-Based Error Handling

When a delegation token is used for an operation outside its granted scopes, the API returns: 
{
  "error": "Insufficient scope for this operation",
  "code": "auth/insufficient-scope"
}
If an invalid scope is requested during authorization: 
{
  "error": "One or more requested scopes are not allowed",
  "code": "auth/scope-not-allowed"
}

​
Rate Limits

The authorize endpoint has a stricter rate limit than other endpoints:
EndpointLimit
POST /v1/authorize100 requests/min per API key
POST /v1/authorize/:id/status100 requests/min per API key
All other endpoints300 requests/min per API key

​
Best Practices

Minimal Scopes

Request only the scopes your platform needs. You can always request additional scopes later with a new authorization.

Secure Token Storage

Store delegation tokens as securely as API keys. They grant access to another business’s UIP capabilities.

Handle Revocation

Delegation tokens can be revoked by the business at any time. Handle auth/invalid-api-key errors gracefully and listen for delegation.revoked webhooks.

Poll with Backoff

Poll the status endpoint every 2-3 seconds with reasonable timeout. The business owner needs time to review and approve.

​
Next Steps

Authorize API

Full API reference for creating authorization sessions

Authorization Status

Check authorization session status

Security

Learn about UIP’s security architecture