Authentication
How to authenticate requests to the Storefront API with an API key and a bearer token.
The Storefront API uses two credentials. The API key identifies the store. The bearer token identifies the signed-in customer.
| Credential | Header | Identifies | Required |
|---|---|---|---|
| API key | x-api-key | The store | On every request |
| Bearer token | Authorization: Bearer <token> | The contact (the signed-in customer) | On requests that act for a contact |
API key
Send the API key of your store in the x-api-key header on every request.
curl "$ONEBASKET_API_URL/catalogues/products" \
-H "x-api-key: $ONEBASKET_API_KEY"Each store has its own API key. Your Stadion technical contact issues it, along with the base URL of each environment.
A request with a missing or invalid API key returns 401 Unauthorized.
Bearer token
Endpoints that read or change data belonging to a customer also need a bearer token. The token is a JSON Web Token (JWT) issued by the organisation's single sign-on system when the customer signs in. OneBasket reads the contact from the token.
curl "$ONEBASKET_API_URL/orders" \
-H "x-api-key: $ONEBASKET_API_KEY" \
-H "Authorization: Bearer $ACCESS_TOKEN"These APIs declare bearer authentication in their OpenAPI documents:
| API | Notes |
|---|---|
| Baskets | A basket can be created and checked out by a guest. Send the token when the customer is signed in so that the basket belongs to the contact. |
| Orders | Returns the orders of the contact in the token. |
| Ticketing | Returns and changes the tickets of the contact in the token. |
| Notifications | |
| Subscriptions | Returns and changes the subscriptions and memberships of the contact in the token. |
| Entitlements | Returns the entitlements of the customer in the token. |
| Payments | Payment provider endpoints. Saved payment methods belong to the contact in the token. |
The Catalogues, Seating, Kiosks and Timestreams APIs need the API key only.
Guest checkout
A customer who is not signed in can still build a basket and check out. Send the API key without a bearer token.
If the customer signs in part way through, call Assign contact with the bearer token to attach the existing basket to the contact.
Keeping credentials safe
- The API key is sent from browsers and mobile apps, so treat it as an identifier of the store and not as a secret that grants administrative access.
- Never log bearer tokens.
- Keep the API key and the base URL in configuration, so that each environment can use its own values.