---
title: "Transient Auth Token"
url: "https://platformdocs.coinme.com/#/docs/transient-auth-token"
markdown: "https://platformdocs.coinme.com/docs/transient-auth-token.md"
summary: "The Vault SDK and the Onboarding SDK submit straight from the customer's browser or app to Coinme, so card numbers and Social Security Numbers never touch your code or your servers, and the Compliance SDK's attestation store reads and records what a customer accepted the same way. Those calls need a credential, and your partner access token is far too powerful to put in a web page or an app. The Transient Auth Token is the credential they carry instead: your backend trades its partner access token for a token that can make one kind of call, for one customer, for ten minutes."
surface: "caas"
platform: "server"
updated: "2026-11-06"
---

# Transient Auth Token

The Vault SDK and the Onboarding SDK submit straight from the customer's browser or app to Coinme, so card numbers and Social Security Numbers never touch your code or your servers, and the Compliance SDK's attestation store reads and records what a customer accepted the same way. Those calls need a credential, and your partner access token is far too powerful to put in a web page or an app. The Transient Auth Token is the credential they carry instead: your backend trades its partner access token for a token that can make one kind of call, for one customer, for ten minutes.

> **Give the Vault SDK, the Onboarding SDK and the Compliance SDK a Transient Auth Token, never your partner access token.**
>
>

The Risk SDK takes neither: its session-tag call needs no token, so never pass it one.

> **After onboarding, every call uses a token for that customer.**
>
> The Onboarding SDK's phone verification (sending the code, checking it) needs a Transient Auth Token with `scope=onboarding` minted for the `customerId` that onboarding returned. Never your partner access token, and never the sign-up session token you onboarded with. That token is the only thing that ties the two calls to the customer: the send carries only the phone number and the check only the code, so there is no challenge ID, session or cookie to pass from one to the other. See [Example: both tokens, end to end](https://platformdocs.coinme.com/docs/transient-auth-token.md#example-both-tokens-end-to-end).

## How the flow works

1. **Your backend gets a partner access token.** It exchanges its API client ID and client secret for a partner access token (`POST /services/authorize`). This token can call every CaaS endpoint on your behalf, so it never leaves your servers.
2. **Your backend mints a Transient Auth Token.** It calls `POST /services/browserAuth` with the partner access token, for the customer adding a card or, for onboarding, the customer's sign-up session. For the Onboarding SDK's phone verification, which follows onboarding, it mints another one for the customer that onboarding created. For the Compliance SDK's attestations, it mints one for the onboarded customer.
3. **Your backend hands it to the client.** Your web page or app receives it over your own authenticated channel and keeps it in memory.
4. **The SDK sends it on the request.** The Vault SDK's payment-method submit, the Onboarding SDK's onboarding submit and phone verification calls, and the Compliance SDK's attestation calls carry it as `Authorization: Bearer <token>`.

The Transient Auth Token is accepted by one kind of call only. Every other Coinme endpoint rejects it, so a leaked token cannot read balances, move funds or reach any other customer.

## Before you start

- **API client credentials.** The client ID and client secret Coinme issued for API access. This client ID is not your partner ID, and it is not the Risk SDK's `clientId`. Keep both in your backend's secret store.
- **The base URL.** Sandbox is `https://caas-staging.coinme.com`; the examples below use it. Your Coinme integration contact provides the production base URL at onboarding.
- **For card capture:** the Coinme `customerId` of the signed-in customer adding the card, and the [Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) in the page or app, since the payment-method submit also carries its `webSessionId` and device fingerprint.
- **For onboarding:** an identifier for the customer's sign-up session in your app. The customer does not exist at Coinme until the onboarding submit succeeds, so the token is minted for that session instead.
- **For phone verification after onboarding:** the Coinme `customerId` the onboarding submit returned. The sign-up session's token does not work for these calls.
- **For attestations:** the Coinme `customerId` of the onboarded customer whose consents and disclosures you read or record.

## Step 1: Get a partner access token

Call this from your backend only. It authenticates with HTTP Basic: your API client ID and client secret, joined by a colon and base64-encoded.

```bash
curl -X POST "https://caas-staging.coinme.com/services/authorize" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)"
```

```json
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": "1800"
}
```

The lifetime differs by environment: 30 minutes (`1800`) in sandbox and 60 minutes (`3600`) in production. Read `expires_in` (seconds, sent as a string) rather than hard-coding it, keep the token in your backend and reuse it until shortly before it expires.

> **Never send the partner access token to a browser or an app.**
>
> It authorizes every CaaS endpoint on your behalf. Only the Transient Auth Token from the next step goes to the client.

## Step 2: Mint a Transient Auth Token

Also from your backend only, authenticated with the partner access token from step 1.

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

| Parameter | In | Required | Notes |
| --- | --- | --- | --- |
| `Authorization` | header | yes | `Bearer <partner access token>`. |
| `customerId` | query | yes | For card capture, the Coinme customer the card will belong to. For onboarding, your identifier for the customer's sign-up session. For phone verification, the Coinme `customerId` onboarding returned, read from your backend's own record, never from the client. For attestations, the Coinme `customerId` of the onboarded customer. The token is bound to this value. |
| `scope` | query | no | `payment-methods` (the default) for the Vault SDK's payment-method submit, `onboarding` for the Onboarding SDK's onboarding submit and phone verification calls (sandbox only for now: Coinme's production environment does not issue tokens with this scope yet), or `attestations` for the Compliance SDK's attestation store, which is not available in the beta at this time. |

For onboarding, pass `scope=onboarding` and the sign-up session's identifier:

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${SIGNUP_SESSION_ID}&scope=onboarding" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

For phone verification, pass `scope=onboarding` and the `customerId` onboarding returned. Mint a fresh one for each verification call (sending the code, checking it), since a customer waiting for the text can easily pass the 10 minutes:

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}&scope=onboarding" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

For the Compliance SDK's attestations, pass `scope=attestations` and the onboarded customer's `customerId`. Attestations are not available in the Compliance SDK beta at this time, and Coinme does not issue tokens with this scope:

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}&scope=attestations" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

```json
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": "600"
}
```

Mint a fresh token each time the customer reaches the add-card, onboarding or consent screen. Tokens last 10 minutes and are cheap to mint; never cache one or reuse it across sessions or customers.

> **Check the body, not just the status.**
>
> A mint that reaches the service but fails validation returns HTTP `200` with an error envelope in the body (for example `{"status":400}`) and no `access_token`. Treat any response without an `access_token` as a failure.

### In your backend

The two calls as a Node.js module. The route that hands the token to your page or app calls `mintTransientAuthToken`: for card capture, for a signed-in customer only; for onboarding, for the customer's sign-up session, because the customer is not signed in yet; for phone verification, for the `customerId` your backend saved against that customer's record when onboarding succeeded, read from your own record and never from the request; for attestations, for the signed-in customer only.

```typescript
const BASE_URL = process.env.COINME_BASE_URL!; // https://caas-staging.coinme.com in sandbox

let partnerToken: { value: string; expiresAt: number } | undefined;

const getPartnerAccessToken = async (): Promise<string> => {
  if (partnerToken && partnerToken.expiresAt > Date.now() + 60_000) {
    return partnerToken.value;
  }
  const credentials = Buffer.from(
    `${process.env.COINME_CLIENT_ID}:${process.env.COINME_CLIENT_SECRET}`
  ).toString('base64');
  const response = await fetch(`${BASE_URL}/services/authorize`, {
    method: 'POST',
    headers: { Authorization: `Basic ${credentials}` },
  });
  const body = await response.json();
  if (!response.ok || !body.access_token) {
    throw new Error(`Coinme authorize failed (${response.status})`);
  }
  partnerToken = {
    value: body.access_token,
    expiresAt: Date.now() + Number(body.expires_in) * 1000,
  };
  return partnerToken.value;
};

export const mintTransientAuthToken = async (
  customerId: string, // or, for onboarding, the sign-up session's identifier
  scope: 'payment-methods' | 'onboarding' | 'attestations' = 'payment-methods'
): Promise<{ token: string; expiresIn: number }> => {
  const url = new URL(`${BASE_URL}/services/browserAuth`);
  url.searchParams.set('customerId', customerId);
  url.searchParams.set('scope', scope);
  const response = await fetch(url, {
    method: 'POST',
    headers: { Authorization: `Bearer ${await getPartnerAccessToken()}` },
  });
  const body = await response.json();
  // A failed mint can arrive as HTTP 200 with an error envelope and no token.
  if (!response.ok || !body.access_token) {
    throw new Error(`Coinme browserAuth failed (${body.status ?? response.status})`);
  }
  return { token: body.access_token, expiresIn: Number(body.expires_in) };
};
```

## Step 3: Hand the token to the client

Deliver the Transient Auth Token to your web page or app over your own authenticated channel, typically the response of the route that serves your add-card, onboarding or consent screen, or a route the client calls just before submitting. Treat it like a session credential:

- Send it only to the signed-in customer, or the sign-up session, it was minted for.
- Keep it in memory. Don't write it to `localStorage`, `sessionStorage`, cookies, device storage or logs.
- If the customer takes longer than 10 minutes, fetch a fresh token from your backend before submitting.

Each SDK takes it where it builds the submit's headers:

| SDK | Where the token goes |
| --- | --- |
| Vault SDK | `Authorization: Bearer <token>` in the `headers` of the payment-method submit; see [Submitting a payment method](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md#submitting-a-payment-method) and each platform's guide. |
| Onboarding SDK | `{ Authorization: 'Bearer <token>' }` returned from `getHeaders`: the form's or provider's for the onboarding submit, the phone verification step's or hook's for the verification calls; see [Authentication and headers](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#authentication-and-headers). |
| Compliance SDK | `{ Authorization: 'Bearer <token>' }` returned from the attestation store's `getHeaders`; see [Attestations](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#attestations). Not available in the beta at this time. |

## Example: both tokens, end to end

> **This is one way to do it, not the only way.**
>
> It shows one way to wire the two Onboarding SDK tokens through a backend. The route names, paths, how your app signs the customer in, the framework and the storage are yours to choose. Only the Coinme API calls and the SDK's props are fixed. It does follow what Coinme recommends:
>
> - your backend reads the `customerId` from its own record, never from the page or app;
> - your partner access token is minted and cached on your server only;
> - each `getHeaders` call fetches a fresh token, kept in memory only and never stored or logged;
> - the phone number is the one from the onboarding result.

Who provides what:

|  | What | Where it runs |
| --- | --- | --- |
| **Coinme provides** | `POST https://caas-staging.coinme.com/services/authorize`: your partner access token (Coinme API) | Called from your backend only |
| **Coinme provides** | `POST https://caas-staging.coinme.com/services/browserAuth`: a Transient Auth Token (Coinme API) | Called from your backend only |
| **Coinme provides** | `CustomerOnboardingForm`, `PhoneVerificationStep` and their props (the Onboarding SDK) | Your page or app |
| **You build** | `POST /your-api/onboarding/token`, `/your-api/onboarding/complete`, `/your-api/phone-verification/token` and `/your-api/phone-verification/verified` | Your backend. These are examples: Coinme doesn't provide them, so name and shape them however you like. |

In production, use the base URL your Coinme integration contact gives you in place of `https://caas-staging.coinme.com`.

### You build

These routes run on **your** backend. Coinme doesn't provide them: the paths are examples, so name them however you like. Only the Coinme API calls they make are fixed.

| Your route (example path) | What it does |
| --- | --- |
| `POST /your-api/onboarding/token` | Mints a Transient Auth Token for the sign-up session: calls Coinme's `POST /services/browserAuth` with `scope=onboarding` and your own ID for the session as `customerId`. Returns `{ token }`. |
| `POST /your-api/onboarding/complete` | Saves the `customerId` and `phoneNumber` from the onboarding result on the signed-in user, in your own database. |
| `POST /your-api/phone-verification/token` | Looks up the signed-in user, reads the `customerId` you saved for them when onboarding succeeded, and mints a Transient Auth Token for **that** `customerId` (`scope=onboarding`). Returns `{ token }`. It never takes a `customerId` from the page or app. |
| `POST /your-api/phone-verification/verified` | Records on the signed-in user that their phone is verified. |

Your partner access token (from Coinme's `POST /services/authorize`) is what these routes use to call `browserAuth`. It stays on your backend and never reaches the page or app.

**This is how customer IDs can't get mixed up.** Each of your users has one saved `customerId`, and the verification token route only ever mints for that one. The page or app never says which customer it is, so it can't ask for the wrong one.

**Your backend** (YOUR code, shown with Express; the routes are examples; `mintTransientAuthToken` is the module from [In your backend](https://platformdocs.coinme.com/docs/transient-auth-token.md#in-your-backend)):

```typescript
import express from 'express';
// Your own code: `requireSession` checks YOUR app's sign-in for the person using it, and `users` is YOUR user store.
import { requireSession, users } from './your-app';
import { mintTransientAuthToken } from './coinme-tokens';

const app = express();
app.use(express.json());

// Token 1: for the sign-up session. The customer doesn't exist at Coinme yet.
app.post('/your-api/onboarding/token', requireSession, async (req, res) => {
  const { token } = await mintTransientAuthToken(req.session.id, 'onboarding');
  res.json({ token });
});

// Save what onboarding returned against YOUR user, so later tokens come from your record.
app.post('/your-api/onboarding/complete', requireSession, async (req, res) => {
  const { customerId, phoneNumber } = req.body;
  await users.update(req.session.userId, {
    coinmeCustomerId: customerId,
    onboardedPhone: phoneNumber,
    phoneVerified: false,
  });
  res.sendStatus(204);
});

// Token 2: for this customer. The page or app never says which customer: the ID comes from
// your record, so a client can only get a token for its own customer.
app.post('/your-api/phone-verification/token', requireSession, async (req, res) => {
  const user = await users.get(req.session.userId);
  if (!user?.coinmeCustomerId) return res.sendStatus(409);
  const { token } = await mintTransientAuthToken(user.coinmeCustomerId, 'onboarding');
  res.json({ token });
});

// The client reports that the code checked out. Coinme checked the code itself.
app.post('/your-api/phone-verification/verified', requireSession, async (req, res) => {
  await users.update(req.session.userId, { phoneVerified: true });
  res.sendStatus(204);
});
```

**Your page or app** (the SDK's `getHeaders` and `onSuccess` props; the React Native SDK takes the same props):

```tsx
// YOUR code, not part of the SDK. These two helpers call routes on YOUR backend (see "You build"
// above). The paths are examples. Keep the tokens in memory only: never store or log them.
const getTokenFromYourBackend = async (path: string): Promise<string> => {
  const response = await fetch(path, { method: 'POST', credentials: 'include' });
  if (!response.ok) throw new Error(`Token request failed (${response.status})`);
  const { token } = await response.json();
  return token;
};

const postToYourBackend = async (path: string, body: unknown): Promise<void> => {
  const response = await fetch(path, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!response.ok) throw new Error(`Request to ${path} failed (${response.status})`);
};

<CustomerOnboardingForm
  environment="sandbox"
  // YOUR backend route. Token 1, fetched fresh before every submit.
  getHeaders={async () => ({
    Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/onboarding/token')}`,
  })}
  // YOUR backend route. Save the result before moving on: token 2 is minted from it.
  onSuccess={(result) => {
    void postToYourBackend('/your-api/onboarding/complete', result).then(() => setOnboarded(result));
  }}
/>;

<PhoneVerificationStep
  environment="sandbox"
  phoneNumber={onboarded.phoneNumber} // the onboarded number, never a new input
  // YOUR backend route. Token 2, fetched fresh before every send and every check. It sends no
  // customerId: your backend already knows which customer this is.
  getHeaders={async () => ({
    Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/phone-verification/token')}`,
  })}
  // YOUR backend route: records that this user's phone is verified.
  onVerified={() => void postToYourBackend('/your-api/phone-verification/verified', {})}
/>;
```

`setOnboarded` is your own state (for example `useState`) that switches the screen from the form to the step. For a complete way to link the `customerId` to your sign-up session, see [Example: linking onboarding to your backend session](https://platformdocs.coinme.com/docs/onboarding-sdk-session-example.md). Don't treat the customer as onboarded until the phone is verified, and send a returning customer whose phone isn't verified back to verification with the number you saved. A real integration also handles a failed request (show a retry).

### Questions about the two tokens

**How do I make sure I don't mix up customer IDs? How does my backend know which customer to mint the verification token for?** From its own records, never from the page or app. When onboarding succeeds, the client sends the result to your backend, which saves the `customerId` on the signed-in user. When the client later asks for the verification token, your backend looks up the signed-in user and mints the token for the `customerId` it saved. Each user has one saved `customerId`, so the client can't ask for someone else's.

**Do I pass the `customerId` to the send or check calls?** No. Neither takes one. The token carries the customer, which is why it has to be minted for that `customerId`.

**Can I use my partner access token for phone verification?** No. It isn't tied to any customer, and it must never reach the browser or app. Use it only on your backend, to mint Transient Auth Tokens.

**Can I reuse the onboarding token?** No. It was minted for the sign-up session, before the customer existed at Coinme. Mint a new one for the `customerId` that onboarding returned.

## What the token allows

- **One kind of call.** A `payment-methods` token is accepted only by the payment-method submit (`POST /services/paymentmethods`); an `onboarding` token only by the Onboarding SDK's onboarding submit and phone verification calls; an `attestations` token only by the Compliance SDK's attestation calls. Any other endpoint, method or path is denied.
- **Ten minutes.** It cannot be refreshed; mint a new one instead.
- **One customer.** It is bound to the `customerId` it was minted for, and a submit for anyone else fails. For phone verification this binding is the only link between the calls and the customer: neither the send nor the check carries a customer ID, challenge ID, session or cookie, so the token you authorize them with decides which customer they act on.
- **Opaque.** It is a signed token, but read nothing from it and build nothing on its contents; they can change.

## Errors and troubleshooting

### Minting

| Response | Cause | Fix |
| --- | --- | --- |
| `200` with body `{"status":400}` | Missing or blank `customerId`. The HTTP status is `200`; the error is in the body. | Send `customerId`, and check the body for `access_token`, not just the HTTP status. |
| `401` `{"message":"Unauthorized"}` | The partner access token is missing, malformed, expired or invalid, or the `Authorization` header is not a Bearer token. | Get a new partner access token (step 1) and retry with `Authorization: Bearer <partner access token>`. |
| `5xx` | A transient service error. | Retry with backoff; if it persists, ask your Coinme integration contact. |

### Submitting

The token most often fails because it expired: customers routinely take longer than 10 minutes to type a card or their details on a phone. Mint when the screen opens, and when a submit fails as unauthorized, fetch a fresh token from your backend and retry the submit once before showing an error.

| SDK | What an expired or rejected token looks like |
| --- | --- |
| Vault SDK | A `CoinmeVaultError` of kind `server` with `status` `401` or `403`. |
| Onboarding SDK | A `CoinmeOnboardingError` of kind `unauthorized`. Phone verification returns it too for a partner access token or the sign-up session token, which are rejected there: mint a fresh token for the onboarded `customerId`. |
| Compliance SDK | A `CoinmeComplianceError` of kind `unauthorized`. |

## Security rules

- **The partner access token stays on your servers.** Only the Transient Auth Token reaches the client.
- **Mint per customer and per session.** Never share a Transient Auth Token between customers, or persist one.
- **Never log tokens** of either kind, in the client or on the server.
- **Keep the client secret in your backend's secret store,** out of source control and out of anything you ship.
- **Let the SDK handle sensitive data.** Card numbers and Social Security Numbers go from the secure fields to Coinme; never put them in `headers` or your own request data.
