Identity server
Connect applications, obtain access tokens, and authorize requests to Graphxsource APIs.
The identity server signs users in and issues tokens that applications send to Graphxsource APIs. It runs on Better Auth with the OAuth provider plugin and Graphxsource extensions for permissions and API key exchange.
You can connect with any OAuth/OIDC library or HTTP client. Your application does not need to run Better Auth, use JavaScript, or share the identity server's framework.
Start with your integration
| You are building | Read |
|---|---|
| An application where a person signs in | Connect a client |
| A job or service that calls an API without a user | Client credentials |
| An API that receives access tokens | Protect a resource |
| An endpoint that checks a user's permissions | Check permissions |
| An integration that holds an organization API key | Exchange an API key |
| A request you need to inspect or reproduce | API reference and troubleshooting |
Clients, resources, and permissions
A client is an application that requests tokens. An OAuth client has a client_id, allowed grants and scopes, and registered redirect URIs. A confidential client also holds credentials, such as a client secret.
A resource is an API that accepts access tokens. Its identifier is an absolute URI, such as https://dev.api.graphxserver.io/orders. The client sends this URI in resource; the API checks that it appears in the token's aud claim. Copy the registered identifier exactly, including any path and trailing slash.
A scope limits what a token can request. A permission answers whether a particular user may perform an action. For example, an API might require the OAuth scope orders.read and a user permission registered in the organization plane. The API must enforce both checks when both apply.
Person -> Client -> Identity server
| sign-in, organization selection, consent
Client <- authorization code
Client -> Identity server: code + PKCE verifier
Client <- access token for a resource
Client -> Resource API: Authorization: Bearer <access_token>
| verify signature, issuer, audience, expiry, scopes
| check user permission and organization when required
Client <- API responseDevelopment endpoints
These URLs refer to the development deployment. Get the issuer and resource identifiers for your target environment from the identity administrator. Keep each environment's clients, credentials, and tokens together.
| Purpose | URL |
|---|---|
| Identity server and token issuer | https://dev.auth.graphxserver.io |
| OIDC discovery | /.well-known/openid-configuration |
| Authorization | https://dev.auth.graphxserver.io/api/auth/oauth2/authorize |
| Token exchange and renewal | https://dev.auth.graphxserver.io/api/auth/oauth2/token |
| Public signing keys | JWKS |
| UserInfo | https://dev.auth.graphxserver.io/api/auth/oauth2/userinfo |
| Token introspection | https://dev.auth.graphxserver.io/api/auth/oauth2/introspect |
| Token revocation | https://dev.auth.graphxserver.io/api/auth/oauth2/revoke |
| Browser API explorer | Live OpenAPI reference |
| OpenAPI JSON | Generated schema |
Use discovery to configure your OAuth/OIDC library. The discovery response supplies the exact issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, and jwks_uri. In this deployment the issuer is the origin, without /api/auth.
curl --fail-with-body \
https://dev.auth.graphxserver.io/.well-known/openid-configurationGather these values before coding
- The issuer and discovery URL for your environment.
- Your
client_id, registered token endpoint authentication method, and secret if applicable. - An exact callback URL for each environment, such as
https://app.example.com/oauth/callback. - The resource identifier of each API you will call and the scopes each endpoint requires.
- The permission keys and organization rules for endpoints that act for a user.
Keep client secrets and refresh tokens in server-side secret storage. The examples use shell variables as placeholders. Do not paste real credentials into documentation, source control, browser bundles, or shared API examples.
Tokens have different jobs
| Credential | Use |
|---|---|
| ID token | Let the client validate the user's sign-in. Validate it with your OIDC library. Its audience is the client. |
| Access token | Call the resource API named by its audience, within its granted scopes. |
| Refresh token | Request replacement tokens at the token endpoint. Never send it to a resource API. |
| Better Auth session cookie or session bearer token | Use the identity server's session APIs. It is a separate credential from an OAuth access token. |
| Organization API key | Exchange it for a resource access token through the Graphxsource extension. |
Use expires_in and the token's verified expiry to decide when to renew. The source configuration defaults to one-hour access tokens and seven-day refresh tokens; a resource policy can override those lifetimes.
The Better Auth session documentation describes identity sessions. The OAuth provider documentation describes OAuth tokens and client registration. This guide describes the Graphxsource configuration and extensions.