Skip to main content

OAuth

OAuth (Open Authorization) is an open standard for access delegation commonly used as a way to enable users to grant websites or applications access to their information without exposing their passwords. It is widely adopted for token-based authentication and authorization in modern applications.

What Is OAuth?​

OAuth enables applications (clients) to access protected resources on behalf of a user (resource owner) without needing to handle or store the user’s login credentials directly.

Instead of credentials, it uses access tokens which are issued by an authorization server and can be used to access APIs on a resource server.

Key Concepts and Terminology​

  • Resource Owner: The user who owns the data or account.
  • Client: The application requesting access to the user's resources.
  • Authorization Server: The server responsible for authenticating the user and issuing access tokens.
  • Resource Server: The server that hosts the protected resources (e.g., APIs).

Common OAuth Flows​

Depending on your application type, one of these flows may be appropriate:

  • Authorization Code Flow (recommended for web/mobile apps)
  • Client Credentials Flow (for server-to-server access)
  • Device Code Flow (for devices without browsers)
  • Resource Owner Password Flow (not recommended unless absolutely necessary)

Authorization Code Flow​

The most common OAuth flow is the Authorization Code Flow, typically used for web and mobile apps. It consists of the following steps:

  1. The client redirects the user to the Authorization Server.
  2. The user logs in and consents to granting access.
  3. The Authorization Server redirects back with an authorization code.
  4. The client exchanges the authorization code for an access token (and optionally a refresh token).

Example (Authorization Code Flow)​

GET /auth?response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/callback
    &scope=read_profile
    &state=random_state_value

Then, to exchange the code:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Client Credentials Flow​

The Client Credentials Flow is used when applications need to authenticate directly with the API — without user interaction. This is ideal for server-to-server communication, such as background jobs, daemons, or backend services.

In this flow, the client authenticates itself with the Authorization Server and receives an access token to access protected resources.

JobRad® API – Client Credentials Flow​

Our APIs use the Client Credentials Flow for secure server-to-server communication.

Token URL:

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

Required Fields:

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

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=dealer-api

Required Scopes:

ScopeDescription
dealer-apiAccess to JobRad® Offers API

⚠️ Do not use this flow in frontend/mobile apps — it exposes client secrets.

OpenID Connect Discovery​

For advanced integration and OpenID Connect discovery, you can retrieve metadata from:

https://id.jobrad.org/realms/external/.well-known/openid-configuration

This endpoint provides metadata such as authorization and token URLs, supported scopes, and more.

Scopes and Permissions​

Scopes define the level of access your application is requesting. They are specified during the authorization request.

Example:

scope=dealer-api

Each API may support different scopes. Refer to the documentation for details.

Security Best Practices​

  • Always use HTTPS.
  • Use PKCE with public clients.
  • Store tokens securely (e.g. Keychain, secure storage).
  • Validate the state parameter to prevent CSRF.
  • Never expose your client_secret in frontend code.

Error Handling​

OAuth errors typically follow this format:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Common errors include:

  • invalid_request
  • invalid_client
  • invalid_grant
  • unauthorized_client
  • unsupported_grant_type