API docs

Reference / Integrator

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.

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_type string required

    always urn:ietf:params:oauth:grant-type:token-exchange

  • subject_token string required

    A Google ID token whose audience is this deployment's origin, such as https://app.booksbyinstant.com in production.

    1 to 4000 characters

  • subject_token_type string required

    always urn:ietf:params:oauth:token-type:id_token

  • requested_token_type string

    always urn:ietf:params:oauth:token-type:access_token

  • resource string

    The 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_token string required

    The integrator credential, or with resource the member token: send it as Authorization: Bearer <token> until it expires.

  • issued_token_type string required

    always urn:ietf:params:oauth:token-type:access_token

  • token_type string required

    always Bearer

  • expires_in integer required

    Whole 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).

  • error string required

    invalid_request for every refusal, whatever its reason; temporarily_unavailable when Instant cannot answer now: wait for Retry-After.

    One of invalid_request temporarily_unavailable

  • error_description string required

    Instant'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-After integer

    Seconds 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-After integer

    Seconds 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.