Transient Auth Token
The short-lived, customer-scoped token your backend mints for the Vault SDK, so your partner access token never reaches a browser or an app.
The Vault SDK submits card data straight from the customer's browser or app to Coinme, so card numbers never touch your code or your servers. That submit needs 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 it carries 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 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.
This page covers the Vault SDK. The same token also authorizes the Onboarding SDK and the Compliance SDK; the Coinme App Platform docs cover all three and are the most current version of this guide.
How the flow works
- 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. - Your backend mints a Transient Auth Token. It calls
POST /services/browserAuthwith the partner access token, for the customer adding a card. - Your backend hands it to the client. Your web page or app receives it over your own authenticated channel and keeps it in memory.
- The SDK sends it on the request. The Vault SDK's payment-method submit carries it as
Authorization: Bearer <transient-auth-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. - The customer. The Coinme
customerIdof the signed-in customer adding the card. - The Risk SDK in the page or app, since the payment-method submit also carries its
webSessionIdand device fingerprint. See Coinme Risk SDK.
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.
curl -X POST "https://caas-staging.coinme.com/services/authorize" \
-H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)"{
"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.
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 | The Coinme customer the card will belong to. The token is bound to this value. |
scope | query | no | payment-methods (the default) for the Vault SDK's payment-method submit. |
{
"access_token": "eyJ…",
"token_type": "Bearer",
"expires_in": "600"
}Mint a fresh token each time the customer reaches the add-card 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
200with an error envelope in the body (for example{"status":400}) and noaccess_token. Treat any response without anaccess_tokenas 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 a signed-in customer only.
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
): Promise<{ token: string; expiresIn: number }> => {
const url = new URL(`${BASE_URL}/services/browserAuth`);
url.searchParams.set('customerId', customerId);
url.searchParams.set('scope', 'payment-methods');
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 screen, or a route the client calls just before submitting. Treat it like a session credential:
- Send it only to the signed-in customer 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.
The Vault SDK takes it as Authorization: Bearer <transient-auth-token> in the headers of the payment-method submit. See each platform's guide:
| Platform | Guide |
|---|---|
| JavaScript | Submitting a payment method |
| React Native | Submitting a payment method |
| iOS | Submitting the data |
| Android | Submitting |
What the token allows
- One kind of call. A
payment-methodstoken is accepted only by the payment-method submit. 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
customerIdit was minted for, and a submit for anyone else fails. - 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, contact your Coinme integration contact. |
Submitting
The token most often fails because it expired: customers routinely take longer than 10 minutes to type a card 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. An expired or rejected token is a server error with status 401 or 403: a CoinmeVaultError of kind server in JavaScript and React Native, CoinmeVaultError.server on iOS and CoinmeVaultException.Server on Android.
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 go from the secure fields to Coinme; never put them in
headersor your own request data.
Updated 25 days ago
