Exchange User 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
-
This parameter is required for clients using form parameters for authentication.
-
This parameter is required for clients using form parameters for authentication and using a client secret as a credential.
-
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
. -
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.
-
Identifies the issuer of the subject_token. The same as the tokens
iss
value. Usually a URL. -
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 providedclient_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
-
This parameter is required for clients using form parameters for authentication.
-
This parameter is required for clients using form parameters for authentication and using a client secret as a credential.
-
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
. -
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.
-
Identifies the issuer of the subject_token. The same as the tokens
iss
value. Usually a URL. -
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 providedclient_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.
-
401 application/json
The authorization of the client is invalid.
-
403 application/json
The token is not trusted and therefore rejected.
-
422 application/json
The request was rejected due to invalid request data, e.g. invalid token content.
-
500 application/json
Internal Server Error.
curl \
-X POST https://api.pace.cloud/user/2023-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/2023-1/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
{
"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"
}
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
{
"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
}
{
"error": "invalid_request",
"error_description": "string",
"error_uri": "string"
}
{
"error": "invalid_request",
"error_description": "string",
"error_uri": "string"
}
{
"error": "invalid_request",
"error_description": "string",
"error_uri": "string"
}
{
"error": "invalid_request",
"error_description": "string",
"error_uri": "string"
}