# Exchange an identity token for a credential or a member token

`POST https://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.

operationId `exchangeToken`; tag Integrator.

## Example request

cURL:

```bash
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:

```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:

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

`application/x-www-form-urlencoded`, required: object; no other fields

These parameters and no others, each at most once: scope, audience, actor_token and client_id are refused too.

- `grant_type` (string; required; always `urn:ietf:params:oauth:grant-type:token-exchange`)
- `subject_token` (string; required; 1 to 4000 characters): A Google ID token whose audience is this deployment's origin, such as https://app.booksbyinstant.com in production.
- `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; at most 300 characters): 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.

## Responses

### 200

The credential or the member token.

`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; at least `0`): Whole seconds until it expires: at most 600, and fewer when the identity token expires sooner.

Example, built from the schema:

```json
{
  "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.

`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; one of `invalid_request`, `temporarily_unavailable`): invalid_request for every refusal, whatever its reason; temporarily_unavailable when Instant cannot answer now: wait for Retry-After.
- `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:

```json
{
  "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; at least `1`): Seconds to wait before retrying.

`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; at least `1`): Seconds to wait before retrying.

`application/json`: the `OAuthError` object, as in 400.

### 5XX

Instant is temporarily unavailable. Retry later, with backoff.

`application/json`: the `OAuthError` object, as in 400.

---

Page: https://booksbyinstant.com/docs/exchange-token/ · Overview: https://booksbyinstant.com/docs/index.md
