# Authenticating with Gladstone APIs > Choose between API key and OAuth2 authentication, and understand what each one is for. HTML version: [Authenticating with Gladstone APIs](https://support.gladstonesoftware.cloud/guides/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](api-key-authentication.md) | | **OAuth2 Authentication** *(Legacy)* | Existing server-to-server integrations using the OAuth2 client-credentials pattern | Client ID + Client Secret + Well-Known configuration | [OAuth2 Authentication](oauth2-authentication.md) | ## 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 | `/api/samlauthentication/partner/token` | `/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 1. [Read the guide that matches your integration type](#at-a-glance). 2. Contact Gladstone Support to be issued credentials and any required configuration (registered origin domain for browser integrations, well-known configuration URL for OAuth2, etc.). 3. 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)