Skip to main content

​
Overview

The amberSearch Public API uses OAuth 2.0 Authorization Code Grant to authenticate third-party applications. This flow allows users to authorize external applications to access amberSearch on their behalf without sharing their credentials.
This is a beta version of our OAuth 2.0 implementation. Features may evolve as we continue to improve the API.

​
Base URL

All OAuth endpoints are available under: 
https://customerDomain.ambersearch.de/api/oauth

​
OAuth 2.0 Flow

The OAuth 2.0 Authorization Code Grant flow consists of the following steps:
1

Client Redirects User to Authorization Endpoint

Your application redirects the user to /api/oauth/authorize with your client credentials and desired scopes.
2

User Authentication

The user authenticates with amberSearch (if not already logged in) and authorizes your application.
3

Authorization Code Issued

amberSearch redirects back to your application’s redirect URI with an authorization code.
4

Exchange Code for Access Token

Your application exchanges the authorization code for an access token by calling /api/oauth/token.
5

Access API with Token

Use the access token to make authenticated requests to amberSearch API endpoints.

​
Getting Started

To use OAuth 2.0 with the amberSearch API, you need OAuth client credentials (client_id and client_secret).
OAuth client credentials can only be obtained from the amberSearch team. Contact your dedicated customer success manager to request your credentials. You cannot generate these credentials yourself.
Once you receive your credentials:
  • Store your client_secret securely (e.g., environment variables, secret management services)
  • Never expose it in client-side code or public repositories
  • Keep your credentials confidential and do not share them

​
Authorization Endpoint

​
Step 1: Redirect User to Authorization

Direct users to the authorization endpoint to begin the OAuth flow: 
GET /api/oauth/authorize
Query Parameters:
ParameterTypeRequiredDescription
response_typestringYesMust be code
client_idstringYesYour OAuth client ID
redirect_uristringYesMust match one of the registered redirect URIs
scopestringNoSpace-separated list of requested scopes
statestringRecommendedOpaque value for CSRF protection
Example Authorization URL: 
https://customerDomain.ambersearch.de/api/oauth/authorize?
  response_type=code&
  client_id=550e8400-e29b-41d4-a716-446655440000&
  redirect_uri=https://myapp.example.com/callback&
  scope=offline_access&
  state=xyz123

​
Step 2: User Authentication

If the user is not logged into amberSearch, they will be redirected to the login page. After successful authentication, they are redirected back to continue the OAuth flow.

​
Step 3: Authorization Response

Upon successful authorization, the user is redirected to your redirect_uri with: 
https://myapp.example.com/callback?code=BASE64_ENCODED_AUTH_CODE&state=xyz123
ParameterDescription
codeThe authorization code (valid for 10 minutes)
stateThe state parameter you provided (verify this matches!)
Error Response: 
https://myapp.example.com/callback?error=access_denied&error_description=User+denied+access

​
Token Endpoint

​
Step 4: Exchange Authorization Code for Access Token

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded
Request Body (form-encoded):
ParameterTypeRequiredDescription
grant_typestringYesMust be authorization_code
codestringYesThe authorization code received
redirect_uristringYesMust match the authorization request
client_idstringYesYour OAuth client ID
client_secretstringYesYour OAuth client secret
Example Request: 
curl -X POST "https://customerDomain.ambersearch.de/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=BASE64_ENCODED_AUTH_CODE" \
  -d "redirect_uri=https://myapp.example.com/callback" \
  -d "client_id=550e8400-e29b-41d4-a716-446655440000" \
  -d "client_secret=your-client-secret"
Success Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": ""
}
Success Response (with offline_access scope): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": null,
  "scope": "offline_access"
}
FieldDescription
access_tokenJWT access token for API requests
token_typeAlways Bearer
expires_inToken lifetime in seconds (3600 = 1 hour, null = permanent)
scopeGranted scopes

​
Using the Access Token

Once you have an access token, include it in the Authorization header for all API requests: 
curl -X GET "https://customerDomain.ambersearch.de/api/beta/search?query=example" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Scopes

ScopeDescription
offline_accessRequest a permanent access token (never expires)
Token Expiration:
  • Standard tokens: Expire after 1 hour (expires_in: 3600)
  • Offline access tokens: Never expire (expires_in: null)
For long-running applications or background processes, request the offline_access scope to avoid token expiration issues.

​
Error Handling

Common OAuth errors:
ErrorDescription
invalid_requestThe request is missing a required parameter or is malformed
unauthorized_clientThe client is not authorized to use this flow
access_deniedThe user denied the authorization request
invalid_grantThe authorization code is invalid or expired
invalid_clientClient authentication failed
Example Error Response: 
{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired"
}

​
Security Best Practices

  • Always use HTTPS for redirect URIs
  • Validate the state parameter to prevent CSRF attacks
  • Store client_secret securely (e.g., environment variables, secret management services)
  • Rotate access tokens regularly if not using offline_access
  • Never expose tokens in URLs or logs