Exchange an identity token for a credential or a member token
POSThttps://app.booksbyinstant.com/api/integrator/v1/token
The OAuth token exchange (RFC 8693) for an integrator whose federation staff turned on: a Google ID token for this deployment's audience, from the service account staff registered as the integrator's trust, for an integrator credential, or with resource a member token, that lasts ten minutes, or less when the identity token expires sooner. There is no refresh: exchange again. Every refusal is the same 400, whatever its reason: the form, the identity token, an unknown trust, federation off, a disabled integrator, a resource that names no active member of the integrator's customers.
exchangeToken · This page as markdown
Example request
cURL
curl -X POST 'https://app.booksbyinstant.com/api/integrator/v1/token' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token=string' \
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:id_token'JavaScript
// Node 18 or later, in an ES module (.mjs), which allows the top-level await.
const res = await fetch("https://app.booksbyinstant.com/api/integrator/v1/token", {
method: "POST",
body: new URLSearchParams({
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token": "string",
"subject_token_type": "urn:ietf:params:oauth:token-type:id_token"
}),
});
const data = await res.json();Python
import requests
res = requests.post(
"https://app.booksbyinstant.com/api/integrator/v1/token",
data={
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token": "string",
"subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
},
)
data = res.json()Authorization
None.
Request body
At most 4096 bytes.
Body application/x-www-form-urlencoded, required
object
These parameters and no others, each at most once: scope, audience, actor_token and client_id are refused too.
no other fields
-
grant_typestring requiredalways
urn:ietf:params:oauth:grant-type:token-exchange -
subject_tokenstring requiredA Google ID token whose audience is this deployment's origin, such as https://app.booksbyinstant.com in production.
1 to 4000 characters
-
subject_token_typestring requiredalways
urn:ietf:params:oauth:token-type:id_token -
requested_token_typestringalways
urn:ietf:params:oauth:token-type:access_token -
resourcestringThe member to act as, by the member's URL in this API: the audience, then /api/integrator/v1/customers/{id}/members/{memberId}. With it the answer is a member token for that member; without it, an integrator credential.
at most 300 characters
Responses
200
The credential or the member token.
Body application/json
object
-
access_tokenstring requiredThe integrator credential, or with
resourcethe member token: send it asAuthorization: Bearer <token>until it expires. -
issued_token_typestring requiredalways
urn:ietf:params:oauth:token-type:access_token -
token_typestring requiredalways
Bearer -
expires_ininteger requiredWhole seconds until it expires: at most 600, and fewer when the identity token expires sooner.
at least
0
Example, built from the schema
{
"access_token": "string",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 0
}400
The form is too large, or a parameter is missing, unknown, given twice or invalid.
Body application/json
object OAuthError
Every answer of the token exchange that is not a success, as an OAuth token endpoint answers (RFC 6749 §5.2).
-
errorstring requiredinvalid_request for every refusal, whatever its reason; temporarily_unavailable when Instant cannot answer now: wait for Retry-After.
One of
invalid_requesttemporarily_unavailable -
error_descriptionstring requiredInstant's sentence for people. A refusal's is always the same: it never says why.
Example, built from the schema
{
"error": "invalid_request",
"error_description": "string"
}429
Too many exchanges in the last minute: 60 for one member, and 6,000 for the integrator, credentials and member tokens together, revoked ones included. Retry after Retry-After seconds, and reuse each token until shortly before it expires. The limits count exchanges already made: exchanges at the same moment can go slightly over the integrator's, while one member's run one at a time.
Headers
-
Retry-AfterintegerSeconds to wait before retrying.
at least
1
Body application/json
The OAuthError object, as in 400.
503
Instant cannot read Google's signing keys, or the exchange is not set up here: retry after Retry-After seconds.
Headers
-
Retry-AfterintegerSeconds to wait before retrying.
at least
1
Body application/json
The OAuthError object, as in 400.
5XX
Instant is temporarily unavailable. Retry later, with backoff.
Body application/json
The OAuthError object, as in 400.