> For the complete documentation index, see [llms.txt](https://developer.usemultiplier.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.usemultiplier.com/api-reference/authentication/oauth.md).
# OAuth
OAuth 2.0 authorization code flow for partner authentication
## OAuth 2.0 Token Exchange
> Implements RFC 8693 (OAuth 2.0 Token Exchange) with extensions.\
> \
> Validates a partner access token and exchanges it for a JWT token. This implementation uses the requested\_subject field (common extension to RFC 8693) to specify the platform user ID for whom the token is being requested.\
> \
> \*\*Security considerations:\*\*\
> \- Uses HTTPS in production (enforced by infrastructure)\
> \- Validates partner access token\
> \- Generates cryptographically secure JWT tokens\
> \
> \*\*Grant Type:\*\*\
> \- Only \`urn:ietf:params:oauth:grant-type:token-exchange\` grant type is supported\
> \
> \*\*Authentication:\*\*\
> \- This endpoint does NOT require a bearer token\
> \- Authentication is performed using the subject\_token in the request body
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization code flow for partner authentication"}],"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[],"paths":{"/authenticate/partner/token-exchange":{"post":{"tags":["OAuth"],"summary":"OAuth 2.0 Token Exchange","description":"Implements RFC 8693 (OAuth 2.0 Token Exchange) with extensions.\n\nValidates a partner access token and exchanges it for a JWT token. This implementation uses the requested_subject field (common extension to RFC 8693) to specify the platform user ID for whom the token is being requested.\n\n**Security considerations:**\n- Uses HTTPS in production (enforced by infrastructure)\n- Validates partner access token\n- Generates cryptographically secure JWT tokens\n\n**Grant Type:**\n- Only `urn:ietf:params:oauth:grant-type:token-exchange` grant type is supported\n\n**Authentication:**\n- This endpoint does NOT require a bearer token\n- Authentication is performed using the subject_token in the request body\n","operationId":"tokenExchange","requestBody":{"description":"OAuth 2.0 token exchange request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_partner_tokenexchange_body"}}},"required":true},"responses":{"200":{"description":"Token exchanged successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200"}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"}}}},"401":{"description":"Invalid partner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"}}}}}}}},"components":{"schemas":{"UserService_partner_tokenexchange_body":{"required":["grant_type","requested_subject","subject_token","subject_token_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"urn:ietf:params:oauth:grant-type:token-exchange\")","enum":["urn:ietf:params:oauth:grant-type:token-exchange"]},"subject_token":{"type":"string","description":"The partner access token to be exchanged"},"subject_token_type":{"type":"string","description":"Token type (must be \"urn:ietf:params:oauth:token-type:access_token\")","enum":["urn:ietf:params:oauth:token-type:access_token"]},"requested_subject":{"type":"string","description":"The platform user ID for whom the token is being requested (extension field)"},"scope":{"type":"string","description":"User scope/role for access permissions","enum":["ADMIN","MANAGER","PAYROLL_ADMIN","BILLING_ADMIN","HR_ADMIN","IT_ADMIN"]}}},"UserService_inline_response_200":{"required":["access_token","expires_in","token_type"],"type":"object","properties":{"access_token":{"type":"string","description":"The access token (JWT) to use for authenticated requests"},"token_type":{"type":"string","description":"Token type (always \"Bearer\")","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Token expiration time in seconds","format":"int64"},"refresh_token":{"type":"string","description":"The refresh token (only included for token-exchange endpoint)"},"customer_user_id":{"type":"string","description":"The customer user ID (UUID). Included when a user was auto-provisioned."}}},"UserService_inline_response_400":{"required":["error"],"type":"object","properties":{"error":{"$ref":"#/components/schemas/UserService_ErrorResponse_error"}},"description":"Standard error response for all API errors"},"UserService_ErrorResponse_error":{"required":["code","message","type"],"type":"object","properties":{"type":{"type":"string","description":"Error category for client-side handling:\n- ValidationError: Request validation failed\n- NotFoundError: Resource doesn't exist\n- ConflictError: Resource already exists or state conflict\n- AuthenticationError: Invalid credentials\n- AuthorizationError: Insufficient permissions\n- ServerError: Unexpected server error\n","enum":["ValidationError","NotFoundError","ConflictError","AuthenticationError","AuthorizationError","ServerError"]},"code":{"type":"string","description":"Common codes:\n- VALIDATION_FAILED: Request validation failed\n- RESOURCE_NOT_FOUND: Resource doesn't exist\n- RESOURCE_ALREADY_EXISTS: Duplicate resource\n- RESOURCE_CONFLICT: State conflict\n- AUTHENTICATION_FAILED: Invalid credentials\n- AUTHORIZATION_FAILED: Insufficient permissions\n- INTERNAL_ERROR: Server error\n","enum":["VALIDATION_FAILED","RESOURCE_NOT_FOUND","RESOURCE_ALREADY_EXISTS","RESOURCE_CONFLICT","AUTHENTICATION_FAILED","AUTHORIZATION_FAILED","INTERNAL_ERROR"]},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Field-level validation errors (only present for validation_error type)","items":{"$ref":"#/components/schemas/UserService_ErrorResponse_error_details"}}}},"UserService_ErrorResponse_error_details":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"Field path using dot notation for nested fields"},"message":{"type":"string","description":"Human-readable error message for this field"}},"description":"Field-level validation error"}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.usemultiplier.com/api-reference/authentication/oauth.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.