Token Management

Tokens are typically short-lived, especially access tokens. To avoid requiring users to log in repeatedly, OAuth may also issue a refresh token, which can be used to obtain new access tokens without additional user interaction.

---

Types of Tokens

• Access Token
  A short-lived token used to authenticate requests to protected resources. It should be included in the Authorization header when making API calls. Once expired, it cannot be reused.

• Refresh Token
  A longer-lived token that allows your app to obtain new access tokens without needing the user to reauthenticate. It should be securely stored and never exposed to the frontend in public clients.

---

Example Token Response

{
  "access_token": "abc123",
  "expires_in": 3600,
  "refresh_token": "def456",
  "token_type": "Bearer",
  "scope": "dealer-api"
}

---

Field Descriptions

Field	Description
access_token	The token used to authenticate API requests. Include it in requests using Authorization: Bearer abc123.
expires_in	The lifetime of the access token in seconds (e.g. 3600 = 1 hour).
refresh_token	The token used to obtain a new access token once the current one expires. Only returned if your app is allowed to refresh tokens.
token_type	Usually "Bearer". Indicates the type of token and how it should be used in the Authorization header.
scope	The scopes granted to the token. This may be a subset of the requested scopes depending on the authorization server’s policy.

---

Refreshing Tokens

When your access token expires, you can use the refresh token to obtain a new one without requiring the user to log in again. This is especially useful for long-lived sessions or background processes that need to maintain access over time.

The request must be made to the token endpoint with grant_type=refresh_token and include the previously received refresh_token, your client credentials, and optionally scopes.

---

Token Endpoint

https://id.jobrad.org/realms/external/protocol/openid-connect/token

---

Example Request

POST https://id.jobrad.org/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

---

Response Example

{
  "access_token": "new-access-token-xyz",
  "expires_in": 3600,
  "refresh_token": "new-refresh-token-abc",
  "token_type": "Bearer",
  "scope": "dealer-api"
}

---

Field Notes

• grant_type: Must be refresh_token to indicate that you're exchanging a refresh token for a new access token.
• refresh_token: The token you previously received and securely stored.
• client_id / client_secret: Identifies your application and must match your credentials registered in the JobRad® system.
• scope (optional): If omitted, the new access token will have the same scope as the original. You can request a reduced scope if needed.

---

Best Practices

• Always store refresh tokens securely (e.g., in secure backend storage).
• Rotate refresh tokens if a new one is issued in the response.
• Implement expiration and revocation checks for refresh tokens.
• Handle token refresh automatically before access tokens expire to avoid request failures.