Authentication
Storefront credentials, Auth API conventions, the token response, and guest sessions
A custom storefront does not use an OAuth redirect flow. There is no hosted login page for customers. You build the login screens, and your server calls the Auth API.
- An owner or admin of your Phasio organisation creates storefront credentials (a client ID and a client secret).
- Your storefront server calls the Auth API with these credentials.
- The Auth API returns an access token (a signed JWT) for a guest or for a signed-in customer.
- Your storefront sends the access token to the Customer API as a Bearer token.
Browser -> Your storefront server -> Auth API (client ID + client secret)
Browser -> Your storefront server -> Customer API (access token)Keep the client secret on your server
Do not put it in browser code, in a mobile app, or in a public repository. The Auth API does not accept calls from browsers (it sends no CORS headers).
The Auth API base URL (AUTH_SERVER) depends on your region. Refer to Base URLs. It is also the token issuer (iss claim). A token from one region is not valid in a different region.
Storefront credentials
To create credentials, refer to Quick start.
- One set of credentials works for your store only. A call for a different store gets the same answer as a call for an unknown store.
- You can have a maximum of 20 active sets of credentials. Use one set for each storefront or environment.
- There is no "rotate" button. To rotate: create new credentials, deploy them, then revoke the old credentials.
- Revoke takes effect immediately. The storefront that uses the revoked credentials loses access.
Your store name
Each call identifies your store by its store name. This is the unique name of your store, the same name that appears in the URL of your Phasio-hosted storefront. The store name must match exactly (it is case-sensitive).
Call conventions
All Auth API endpoints, except PATCH /customer/login/reset:
- use the method
POST - need the header
Authorization: Basic base64(<client ID>:<client secret>) - need the header
Content-Type: application/json - accept a JSON body of maximum 100 KB
Do not forward browser cookies or the browser Origin header to the Auth API.
Token response
A successful sign-in returns a token response:
{
"scope": "CUSTOMER",
"access_token": "<JWT>",
"refresh_token": "",
"token_type": "Bearer",
"expires_in": 32400
}scopeisCUSTOMERfor a signed-in customer andANONYMOUSfor a guest.expires_inis 32400 seconds (9 hours).refresh_tokenis always empty. There is no refresh. Refer to Lifetime, refresh, and sign-out.
Errors
Errors return a JSON body with a message field. Use the HTTP status code in your logic, not the message text.
{ "message": "valid storefront credentials are required" }Missing, incorrect, or revoked credentials always give 401.
Guest sessions
A guest session lets a visitor use the storefront before sign-in, for example to upload parts and to build a cart.
If your store setting loginStage is BEFORE_PRICE, ask the visitor to sign in before uploads and prices, and skip guest sessions.
POST /customer/anonymous
Request:
{ "store": "your-store-name" }Response 200: a token response with "scope": "ANONYMOUS".
| Status | Meaning |
|---|---|
400 | store is empty |
404 | The store is unknown, or the credentials are not for this store |
429 | Too many requests |
Guidance
- Each call makes a new, independent guest. Get one guest token for each visitor, keep it for the visit, and get a new one a short time before it expires.
- Do not get a new guest token on each page load. Refer to Rate limits.
- When the guest signs in, move the guest's parts and carts to the customer account. Refer to Claim the guest cart.
Features that are not available
- Magic links
- Social sign-in and single sign-on for customers
- Sign-up with a phone number
Last updated on