# Exchange User Token **POST /protocol/openid-connect/token** Creates a PACE token for a foreign token using the OIDC token-exchange. The token provided **must** include the following claims (see https://datatracker.ietf.org/doc/html/rfc7519#page-9): * Claim `aud`: e.g. `"api.pace.cloud"` audience of this token is PACE API, has to match the host requested via HTTP. In development or other environments the URL may be different therefore, e.g. `"api.dev.pace.cloud"`. * Claim `iss`: e.g. `"https://as.example.com"` the issuer of the token, issuer needs to be known to PACE * Claim `iat`: e.g. `1516239022` time the token was issued * Claim `exp`: e.g. `1516249022` identifies the expiration time on or after which the JWT MUST NOT be accepted for processing * Claim `sub`: e.g. `"03836e1f-58ed-4d67-baa0-a73bf77b9d5d"` unique account id on the issuer side * Claim `email`: e.g. `"03836e1f-58ed-4d67-baa0-a73bf77b9d5d@as.example.com"` usually an account proxy email (will receive SMTP mails). Usually subject ID + issuer domain to provide a unique account id. Optionally the token may contain: * Claim `name`: e.g. `"Jane Doe"` full name of the user (used in emails addressed to the proxy) * Claim `given_name`: e.g. `"Jane"` given name of the user * Claim `family_name`: e.g. `"Doe"` family name of the user * Claim `locale`: e.g. `"de"` or `"en-US"` language code of the user (format ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash) defaults to `"en"` * Claim `zoneinfo`: e.g. `"Europe/Paris"` timezone information defaults to `"Europe/Berlin"` (TZ database) RFCs for reference: * https://datatracker.ietf.org/doc/html/rfc8693 * https://datatracker.ietf.org/doc/html/rfc7519 ## Servers - Preview: https://api.pace.cloud/user/2022-1 (Preview) ## Parameters ## Body parameters Content-type: application/json - **client_id** (string) This parameter is required for clients using form parameters for authentication. - **client_secret** (string) This parameter is required for clients using form parameters for authentication and using a client secret as a credential. - **grant_type** (string) The value of the parameter must be `urn:ietf:params:oauth:grant-type:token-exchange`. - **subject_token** (string) A security token that represents the identity of the party on behalf of whom the request is being made. It is required if you are exchanging an existing token for a new one. - **subject_issuer** (string) Identifies the issuer of the subject_token. The same as the tokens `iss` value. Usually a URL. - **subject_token_type** (string) This parameter represents the type of token the client wants to exchange for. Currently only oauth and OpenID Connect token types are supported specifically `urn:ietf:params:oauth:token-type:access_token`. - **audience** (string) This parameter specifies the target client you want the new token minted for. This will be part of the token in the `aud` field. If left blank it will be the same as the provided `client_id`. - **scope** (string) This parameter represents the target set of OAuth and OpenID Connect scopes the client is requesting. This parameter ensures to the client that the token is only provided in case the requested scopes are part of it. More scopes may be returned. ## Responses ### 200: PACE Access Token. #### Body Parameters: application/json (object) - **access_token** (string) - **issued_token_type** (string) The type of the token issued as described. - **token_type** (string) The type of the token issued as described in https://datatracker.ietf.org/doc/html/rfc6749#section-7.1. Value is case insensitive. - **expires_in** (number) The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value. ### 401: The authorization of the client is invalid. #### Body Parameters: application/json (object) - **error** (string) A single ASCII [USASCII] error code from the following: **invalid_request** The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. **invalid_client** Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. **invalid_grant** The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. **unauthorized_client** The authenticated client is not authorized to use this authorization grant type. **unsupported_grant_type** The authorization grant type is not supported by the authorization server. - **error_description** (string) Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. - **error_uri** (string) A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. ### 403: The token is not trusted and therefore rejected. #### Body Parameters: application/json (object) - **error** (string) A single ASCII [USASCII] error code from the following: **invalid_request** The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. **invalid_client** Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. **invalid_grant** The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. **unauthorized_client** The authenticated client is not authorized to use this authorization grant type. **unsupported_grant_type** The authorization grant type is not supported by the authorization server. - **error_description** (string) Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. - **error_uri** (string) A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. ### 422: The request was rejected due to invalid request data, e.g. invalid token content. #### Body Parameters: application/json (object) - **error** (string) A single ASCII [USASCII] error code from the following: **invalid_request** The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. **invalid_client** Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. **invalid_grant** The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. **unauthorized_client** The authenticated client is not authorized to use this authorization grant type. **unsupported_grant_type** The authorization grant type is not supported by the authorization server. - **error_description** (string) Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. - **error_uri** (string) A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. ### 500: Internal Server Error. #### Body Parameters: application/json (object) - **error** (string) A single ASCII [USASCII] error code from the following: **invalid_request** The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. **invalid_client** Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. **invalid_grant** The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. **unauthorized_client** The authenticated client is not authorized to use this authorization grant type. **unsupported_grant_type** The authorization grant type is not supported by the authorization server. - **error_description** (string) Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. - **error_uri** (string) A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. [Powered by Bump.sh](https://bump.sh)