Authenticating with Gladstone APIs
There are two ways to authenticate with the Gladstone API. For new integrations we recommend API Key Authentication — it supports member-scoped tokens, refresh tokens, and per-integration rate limiting. OAuth2 Authentication is still fully supported for existing integrations but is not the recommended choice for new ones.
Both flows end with you holding a JWT bearer token that you send on every downstream API call.
At a glance
| Method | Best for | Credentials issued | Guide |
|---|---|---|---|
| API Key Authentication (Recommended) | Third-party web / mobile integrations needing member-scoped tokens, refresh tokens, per-integration rate limiting, audit logs, and registered-origin browser support | Partner API Key (format gsk_{version}_{secret}) | API Key Authentication |
| OAuth2 Authentication (Legacy) | Existing server-to-server integrations using the OAuth2 client-credentials pattern | Client ID + Client Secret + Well-Known configuration | OAuth2 Authentication |
Which should I use?
- Use API Key Authentication (recommended for new integrations) if you're building a
web or mobile integration that needs to act on behalf of an individual member, you want
token refresh built in, or you've been issued a partner API key (
gsk_…format). - Use OAuth2 Authentication (legacy — still supported) if you already have an OAuth2 client-credentials integration with Gladstone, or you've specifically been issued a Client ID + Client Secret. New integrations should default to API Key Authentication.
If you're unsure which applies to your integration, ask the Gladstone team — they decide which credential type to issue based on your integration use case.
What both flows have in common
- Bearer JWTs. Both produce a JWT that you send as
Authorization: Bearer ***on every API call. The downstream Gladstone APIs accept either token type the same way. - Token-based, not cookie-based. Neither flow uses cookies; both work cross-domain.
How they differ
| Concern | API Key Authentication (Recommended) | OAuth2 Authentication (Legacy) |
|---|---|---|
| Credential type | API Key (gsk_{version}_{secret}) | Client ID + Client Secret |
| Token endpoint | <environment>/api/samlauthentication/partner/token | <environment>/identity/connect/token |
| Grant types supported | API-only (machine-to-machine), member-scoped (email+password), refresh | client_credentials |
| Refresh tokens | Issued alongside every access token; refresh without re-entering credentials | Not issued — re-authenticate when the token expires |
| Acting on behalf of a member | Supported via the member-scoped grant | Not supported |
| Origin lock (browser) | Browser callers must send Origin matching the registered domain | Not enforced |
| Per-integration rate limits | Per-minute and per-hour limits enforced; 429 + Retry-After | Not configured |
| Audit logging | Dedicated audit log per API key — visible to Gladstone administrators | Standard service logs |
| Credential rotation | API Key can be revoked / renewed by the operator at any time | Client Secret can be rotated by Gladstone Support |
Product and feature entitlements
Holding a valid token is not the same as being allowed to call an endpoint. Authentication proves who you are; entitlements decide which endpoints that identity may reach.
Every endpoint page in this documentation carries an Access requirements panel below the
method and path, listing the products and features that endpoint demands. Read it before
you write the call — it is the difference between a working integration and a 403 you cannot
explain.
The panel names each product and feature as you would hear it referred to — Operator, Consumer, Online Bookings. Each one also has a short upper-case code, which is what the platform matches on internally; hover a name to see it. Quote the code when you raise a ticket, because that is the form Gladstone Support and the gateway both use.
Three rules govern how those lists are read:
- A list means any one of, not all of. An endpoint requiring Operator and Consumer admits a token granted either. You do not need both, and asking to be granted both will not change the outcome.
- An empty requirement means no check. Where a panel says an endpoint is not restricted by product, the gateway does not examine the product claim at all. That is a different statement from "requires a product you probably have", and it will not start being enforced without the endpoint's documentation changing.
- Entitlements are granted to your integration, not inherited from the operator. The modules enabled for the operator you are integrating with are not automatically available to you. Your integration is granted its own set, and a module granted to it satisfies both the product and the feature requirement of that name.
When a token reaches an endpoint without an entitlement it requires, the gateway refuses the
request with 403 before it reaches the service — so the response carries no business detail
explaining the refusal. A 403 on an endpoint you believe you should be able to call is almost
always a missing grant rather than a malformed request: check the Access requirements panel, then
ask Gladstone Support to grant the missing module. Contrast this with a 401, which means the
token itself was missing, expired or revoked.
Entitlements are fixed at the point your token is issued. If Gladstone grants your integration a new module, request a fresh token before expecting the new endpoints to answer.
Common pitfalls (both flows)
- Never embed credentials in browser JavaScript or any client-side code. Always store on a backend / secret manager.
- Handle
401— both credential types can be revoked / rotated. Your integration must re-authenticate cleanly when the gateway rejects a token. - Honour the JWT lifetime returned in
expires_in/expiresIn. Don't hardcode a duration; the configured lifetime can vary per environment.
Get started
- Read the guide that matches your integration type.
- Contact Gladstone Support to be issued credentials and any required configuration (registered origin domain for browser integrations, well-known configuration URL for OAuth2, etc.).
- Implement the relevant flow, then send
Authorization: Bearer ***on every API call.
Support
For credential setup, renewal, or troubleshooting either flow, contact Gladstone Support. When reporting issues please include:
- Approximate timestamp (UTC)
- Endpoint called
- HTTP status code received
- Response body (redact any tokens / keys)