Authentication Guide
This guide describes how to interact with the GoodBridge Auth Server to obtain and refresh authentication tokens.
1. Getting an Access Token
To obtain a new access_token and refresh_token, use the client_credentials grant type.
Endpoint: POST /oauth/token
Request body:
{
"grant_type": "client_credentials",
"client_id": "your-client-id",
"client_secret": "your-client-secret"
}
Successful Response:
access_token(string): Token used to authorize requests to protected services.refresh_token(string): Token used to get a new access token when the current one expires.access_expires_at(datetime): Expiration time of the access token (ISO 8601).refresh_expires_at(datetime): Expiration time of the refresh token (ISO 8601).token_type(string): Usually “bearer”.
2. Refreshing an Access Token
When your access_token expires, you can use the refresh_token to obtain a new pair of tokens without re-authenticating with client credentials.
Endpoint: POST /oauth/token
Request body:
{
"grant_type": "refresh",
"refresh_token": "your-refresh-token"
}
Successful Response:
The response structure is the same as when obtaining tokens for the first time.
3. Using the Access Token
Include the access_token in the Authorization header of your HTTP requests to protected microservices:
Authorization: Bearer <access_token>
4. Revoking a Token
If you need to manually invalidate a token (e.g., during logout), use the /oauth/revoke endpoint.
Endpoint: DELETE /oauth/revoke
Request parameters (query):
token(string): The token you want to revoke.token_type_hint(string): Type of the token, eitheraccessorrefresh.
Example:
DELETE /oauth/revoke?token=<your_token>&token_type_hint=access
5. Token Introspection
To check if a token is still valid and get its metadata, use the /oauth/introspect endpoint.
Endpoint: GET /oauth/introspect
Request parameters (query):
access_token(string): The token to introspect.
Example:
GET /oauth/introspect?access_token=<your_access_token>
Response:
{
"is_active": true,
"client_id": "your-client-id",
"expires_at": 1711814040.0
}