> 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/magic-links.md).
# Magic Links
Authorization code generation and exchange for seamless user authentication
## Generate Authorization Code
> Generates an authorization code for a strategic partner customer user.\
> \
> Extracts partner ID from the JWT token in the Authorization header,\
> looks up the platform user ID, and generates a short-lived auth code.\
> \
> \*\*Security considerations:\*\*\
> \- Requires valid Bearer token in Authorization header\
> \- Auth code is short-lived (typically 60 seconds)\
> \- Auth code can only be used once\
> \
> \*\*Authentication:\*\*\
> \- Requires Bearer token in Authorization header
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Magic Links","description":"Authorization code generation and exchange for seamless user 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":[{"bearerAuth":[]}],"components":{"securitySchemes":{},"schemas":{"UserService_partner_requestauthcode_body":{"type":"object","properties":{"customerUserId":{"type":"string","description":"The customer user ID for which to generate the auth code (UUID). Either this or (customerId+email+firstName+lastName) must be provided."},"customerId":{"type":"string","description":"The customer ID for auto-provisioning. Required if customerUserId is not provided."},"email":{"type":"string","description":"User email for auto-provisioning. Required if customerUserId is not provided.","format":"email"},"firstName":{"type":"string","description":"User first name for auto-provisioning. Required if customerUserId is not provided."},"lastName":{"type":"string","description":"User last name for auto-provisioning. Required if customerUserId is not provided."},"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_1":{"required":["auth_code","expires_in"],"type":"object","properties":{"auth_code":{"type":"string","description":"The generated authorization code"},"expires_in":{"type":"integer","description":"Auth code expiration time in seconds","format":"int64"},"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"}}},"paths":{"/authenticate/partner/request-authcode":{"post":{"tags":["Magic Links"],"summary":"Generate Authorization Code","description":"Generates an authorization code for a strategic partner customer user.\n\nExtracts partner ID from the JWT token in the Authorization header,\nlooks up the platform user ID, and generates a short-lived auth code.\n\n**Security considerations:**\n- Requires valid Bearer token in Authorization header\n- Auth code is short-lived (typically 60 seconds)\n- Auth code can only be used once\n\n**Authentication:**\n- Requires Bearer token in Authorization header\n","operationId":"requestAuthCode","parameters":[{"name":"Authorization","in":"header","description":"Bearer token for partner authentication","required":true,"style":"simple","explode":false,"schema":{"type":"object"}}],"requestBody":{"description":"Auth code generation request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_partner_requestauthcode_body"}}},"required":true},"responses":{"200":{"description":"Auth code generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200_1"}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"}}}},"401":{"description":"Invalid or missing authorization 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"}}}}}}}}}
```
## Generate Authorization Code for Customer User
> Generates an authorization code for a customer user using a platform JWT token.\
> \
> This endpoint extracts the platform user ID directly from the JWT token's claims\
> (details.id field) and generates a short-lived auth code.\
> \
> Unlike /authenticate/partner/request-authcode, this endpoint:\
> \- Does NOT require a customerUserId in the request body\
> \- Accepts only platform JWT tokens (not client auth tokens)\
> \- Extracts platformUserId from the JWT token's "details.id" claim\
> \
> \*\*Security considerations:\*\*\
> \- Requires valid Bearer token (platform JWT) in Authorization header\
> \- Auth code is short-lived (typically 60 seconds)\
> \- Auth code can only be used once\
> \
> \*\*Authentication:\*\*\
> \- Requires Bearer token (platform JWT) in Authorization header
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Magic Links","description":"Authorization code generation and exchange for seamless user 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":[{"bearerAuth":[]}],"components":{"securitySchemes":{},"schemas":{"UserService_inline_response_200_1":{"required":["auth_code","expires_in"],"type":"object","properties":{"auth_code":{"type":"string","description":"The generated authorization code"},"expires_in":{"type":"integer","description":"Auth code expiration time in seconds","format":"int64"},"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"}}},"paths":{"/authenticate/partner/request-customer-authcode":{"post":{"tags":["Magic Links"],"summary":"Generate Authorization Code for Customer User","description":"Generates an authorization code for a customer user using a platform JWT token.\n\nThis endpoint extracts the platform user ID directly from the JWT token's claims\n(details.id field) and generates a short-lived auth code.\n\nUnlike /authenticate/partner/request-authcode, this endpoint:\n- Does NOT require a customerUserId in the request body\n- Accepts only platform JWT tokens (not client auth tokens)\n- Extracts platformUserId from the JWT token's \"details.id\" claim\n\n**Security considerations:**\n- Requires valid Bearer token (platform JWT) in Authorization header\n- Auth code is short-lived (typically 60 seconds)\n- Auth code can only be used once\n\n**Authentication:**\n- Requires Bearer token (platform JWT) in Authorization header\n","operationId":"requestCustomerAuthCode","parameters":[{"name":"Authorization","in":"header","description":"Bearer token (platform JWT) for authentication","required":true,"style":"simple","explode":false,"schema":{"type":"object"}}],"responses":{"200":{"description":"Auth code generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200_1"}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"}}}},"401":{"description":"Invalid or missing authorization 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"}}}}}}}}}
```
## OAuth 2.0 Authorization Code Exchange
> Implements RFC 6749 Section 4.1.3 - Authorization Code Grant.\
> \
> Exchanges an authorization code for access and refresh tokens.\
> \
> \*\*Security considerations:\*\*\
> \- Uses HTTPS in production (enforced by infrastructure)\
> \- Auth code is single-use and short-lived\
> \- Validates client\_id\
> \
> \*\*Grant Type:\*\*\
> \- Only \`authorization\_code\` grant type is supported\
> \
> \*\*Authentication:\*\*\
> \- This endpoint does NOT require a bearer token\
> \- Authentication is performed using the authorization code
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Magic Links","description":"Authorization code generation and exchange for seamless user 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/authcode":{"post":{"tags":["Magic Links"],"summary":"OAuth 2.0 Authorization Code Exchange","description":"Implements RFC 6749 Section 4.1.3 - Authorization Code Grant.\n\nExchanges an authorization code for access and refresh tokens.\n\n**Security considerations:**\n- Uses HTTPS in production (enforced by infrastructure)\n- Auth code is single-use and short-lived\n- Validates client_id\n\n**Grant Type:**\n- Only `authorization_code` grant type is supported\n\n**Authentication:**\n- This endpoint does NOT require a bearer token\n- Authentication is performed using the authorization code\n","operationId":"exchangeAuthCode","parameters":[{"name":"platform","in":"header","description":"Optional platform type for refresh token cookie","required":false,"style":"simple","explode":false,"schema":{"type":"object","enum":["web","mobile"]}}],"requestBody":{"description":"OAuth 2.0 authorization code exchange request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_partner_authcode_body"}}},"required":true},"responses":{"200":{"description":"Tokens issued 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 authorization code or client credentials","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_authcode_body":{"required":["client_id","code","grant_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"authorization_code\")","enum":["authorization_code"]},"code":{"type":"string","description":"The authorization code from the partner"},"client_id":{"type":"string","description":"The client identifier"}}},"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/magic-links.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.