Exchange User Token | User API documentation (2022-1)

Exchange User Token Deprecated

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:

Body Required

client_id string Required

This parameter is required for clients using form parameters for authentication.
client_secret string Required

This parameter is required for clients using form parameters for authentication and using a client secret as a credential.
grant_type string Required

The value of the parameter must be urn:ietf:params:oauth:grant-type:token-exchange.

Value is urn:ietf:params:oauth:grant-type:token-exchange.
subject_token string Required

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 Required

Identifies the issuer of the subject_token. The same as the tokens iss value. Usually a URL.
subject_token_type string Required

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.

Value is 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.

Body Required

client_id string Required

This parameter is required for clients using form parameters for authentication.
client_secret string Required

This parameter is required for clients using form parameters for authentication and using a client secret as a credential.
grant_type string Required

The value of the parameter must be urn:ietf:params:oauth:grant-type:token-exchange.

Value is urn:ietf:params:oauth:grant-type:token-exchange.
subject_token string Required

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 Required

Identifies the issuer of the subject_token. The same as the tokens iss value. Usually a URL.
subject_token_type string Required

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.

Value is 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 application/json

PACE Access Token.
Hide response attributes Show response attributes object
- access_token string Required
- issued_token_type string Required
  
  The type of the token issued as described.
  
  Value is urn:ietf:params:oauth:token-type:jwt.
- token_type string Required
  
  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 Required
  
  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 application/json

The authorization of the client is invalid.
Hide response attributes Show response attributes 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.
  
  Values are invalid_request, invalid_client, invalid_grant, unauthorized_client, or unsupported_grant_type.
- 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 application/json

The token is not trusted and therefore rejected.
Hide response attributes Show response attributes 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.
  
  Values are invalid_request, invalid_client, invalid_grant, unauthorized_client, or unsupported_grant_type.
- 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 application/json

The request was rejected due to invalid request data, e.g. invalid token content.
Hide response attributes Show response attributes 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.
  
  Values are invalid_request, invalid_client, invalid_grant, unauthorized_client, or unsupported_grant_type.
- 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 application/json

Internal Server Error.
Hide response attributes Show response attributes 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.
  
  Values are invalid_request, invalid_client, invalid_grant, unauthorized_client, or unsupported_grant_type.
- 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.

POST /protocol/openid-connect/token

curl \
 -X POST https://api.pace.cloud/user/2022-1/protocol/openid-connect/token \
 -H "Content-Type: application/json" \
 -d '{"client_id":"awesome-app","client_secret":"aad041a4-47f0-4b01-80d3-edce807fec82","grant_type":"urn:ietf:params:oauth:grant-type:token-exchange","subject_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMzgzNm UxZi01OGVkLTRkNjctYmFhMC1hNzNiZjc3YjlkNWQiLCJhdWQiOiJhc GkuZGV2LnBhY2UuY2xvdWQiLCJuYW1lIjoiSmFuZSBEb2UiLCJnaXZl bl9uYW1lIjoiSmFuZSIsImZhbWlseV9uYW1lIjoiRG9lIiwiaXNzIjo iaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImlhdCI6MTUxNjIzOTAyMi wiZXhwIjoxNTE2MjQ5MDIyLCJlbWFpbCI6IjAzODM2ZTFmLTU4ZWQtN GQ2Ny1iYWEwLWE3M2JmNzdiOWQ1ZEBhcy5leGFtcGxlLmNvbSJ9.Z1t -0dayzXl069Bwt5bHlgpV0WlZUKF5ma7X1Uo-e3o\n","subject_issuer":"https://as.example.com","subject_token_type":"urn:ietf:params:oauth:token-type:access_token","audience":"awesome-app","scope":"string"}'

curl \
 -X POST https://api.pace.cloud/user/2022-1/protocol/openid-connect/token \
 -H "Content-Type: application/x-www-form-urlencoded" \

Request examples

{
  "client_id": "awesome-app",
  "client_secret": "aad041a4-47f0-4b01-80d3-edce807fec82",
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMzgzNm UxZi01OGVkLTRkNjctYmFhMC1hNzNiZjc3YjlkNWQiLCJhdWQiOiJhc GkuZGV2LnBhY2UuY2xvdWQiLCJuYW1lIjoiSmFuZSBEb2UiLCJnaXZl bl9uYW1lIjoiSmFuZSIsImZhbWlseV9uYW1lIjoiRG9lIiwiaXNzIjo iaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImlhdCI6MTUxNjIzOTAyMi wiZXhwIjoxNTE2MjQ5MDIyLCJlbWFpbCI6IjAzODM2ZTFmLTU4ZWQtN GQ2Ny1iYWEwLWE3M2JmNzdiOWQ1ZEBhcy5leGFtcGxlLmNvbSJ9.Z1t -0dayzXl069Bwt5bHlgpV0WlZUKF5ma7X1Uo-e3o\n",
  "subject_issuer": "https://as.example.com",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "audience": "awesome-app",
  "scope": "string"
}

Request example

client_idawesome-app&client_secretaad041a4-47f0-4b01-80d3-edce807fec82&grant_typeurn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&subject_tokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMzgzNm%20UxZi01OGVkLTRkNjctYmFhMC1hNzNiZjc3YjlkNWQiLCJhdWQiOiJhc%20GkuZGV2LnBhY2UuY2xvdWQiLCJuYW1lIjoiSmFuZSBEb2UiLCJnaXZl%20bl9uYW1lIjoiSmFuZSIsImZhbWlseV9uYW1lIjoiRG9lIiwiaXNzIjo%20iaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImlhdCI6MTUxNjIzOTAyMi%20wiZXhwIjoxNTE2MjQ5MDIyLCJlbWFpbCI6IjAzODM2ZTFmLTU4ZWQtN%20GQ2Ny1iYWEwLWE3M2JmNzdiOWQ1ZEBhcy5leGFtcGxlLmNvbSJ9.Z1t%20-0dayzXl069Bwt5bHlgpV0WlZUKF5ma7X1Uo-e3o%0A&subject_issuerhttps%3A//as.example.com&subject_token_typeurn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token&audienceawesome-app

Response examples (200)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJnYlpySmRJelBTTWN 1aHNJYzZfM3g3ZmhrdTM4UmN5MlZLVUZ4LWppNTNzIn0.eyJleHAiOjE2MjU4MzcyOT AsImlhdCI6MTYyNTgzMDA5MCwiYXV0aF90aW1lIjoxNjI1ODMwMDQ4LCJqdGkiOiIyM 2FiNzEwMC0xZGZkLTQwYTktYTE3YS01MjUwN2ZlYWFiY2IiLCJpc3MiOiJodHRwczov L2lkLmRldi5wYWNlLmNsb3VkL2F1dGgvcmVhbG1zL3BhY2UiLCJzdWIiOiI1YWE2NWY 1NC01NjdmLTQ2ZTUtYWRkOS05OGIxMjQ0YjUzMTYiLCJ0eXAiOiJCZWFyZXIiLCJhen AiOiJ2aW5jZW50LXRlc3QtMiIsInNlc3Npb25fc3RhdGUiOiIzYTMwMDM1OC0xMzIyL TRlYzktYWI3My1kYjM5MjUwYzIzZjQiLCJhY3IiOiIwIiwic2NvcGUiOiJka3ZjYXJk OnBheW1lbnQtbWV0aG9kOmFkZCB1c2VyOnVzZXIuZW1haWw6cmVhZCB1c2VyOnByZWZ lcmVuY2VzOndyaXRlIHVzZXI6cHJlZmVyZW5jZXM6cmVhZCBmdWVsY2FyZDpjYXJkcz pyZWFkIHBvaTpnYXMtc3RhdGlvbnM6cmVhZCBka3ZjYXJkOmNhcmRzOnJlYWQgZGt2Y 2FyZDpwYXltZW50LW1ldGhvZDpyZW1vdmUiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwi bG9jYWxlIjoiZGUiLCJlbWFpbCI6ImphbmUuZG9lQGV4YW1wbGUtcGFsY2UtaW4tdGh lLXd3dy5jb20ifQ.mp4mkpPPMpFfZa5cYiTDM8HxFsEMKVm_B6ujh_629sHc6D7iaCg jUZ2VNwGyxDS2Z_XZ-b2PoLVLHJOS2shBVS7p-kx7fFuCCMA9Um-3RpIzfVNyYbNiHX T2DG146845Jxdfa5S3nAuaD5_aFOKEcQQpXEMqVm5QTfD1cU8ne61mOF34_CbW_c7kX bVJKCYv-qg0LzKfhO6xeGe5ovo3-QWZCXtQmhsCcK2HnQ6kgDLAK_vdSHkvNR3lEv_i H83DyqGysXvVdvT6f25CcVabTBCcnpyKHC3765p_tkZ2digX_qm8KBVKIAN00UP6f2V c0VEGKIAlfNZlC1hMpWxCEA\n",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 7200
}

Response examples (401)

{
  "error": "invalid_request",
  "error_description": "string",
  "error_uri": "string"
}

Response examples (403)

{
  "error": "invalid_request",
  "error_description": "string",
  "error_uri": "string"
}

Response examples (422)

{
  "error": "invalid_request",
  "error_description": "string",
  "error_uri": "string"
}

Response examples (500)

{
  "error": "invalid_request",
  "error_description": "string",
  "error_uri": "string"
}