Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.ambersearch.de/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The amberSearch Public API uses OAuth 2.0 Authorization Code Grant and a PKCE safety measure to authenticate third-party applications. This flow allows users to authorize external applications to access amberSearch on their behalf without sharing their credentials. The provider abides by the specifications defined in the RFC 6749 and RFC 7636 protocols, implementing a seamless and secure interface for authorizing users.
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, client_secret or simply client_id if PKCE is required.
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.

​
Discovery Endpoints

To make integration easier, amberSearch exposes OAuth discovery endpoints so clients can automatically learn: • the authorization endpoint (/authorize) • the token endpoint (/token) • supported PKCE methods • supported scopes 
GET /.well-known/oauth-authorization-server

​
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
code_challengestringYesEncoded version of the code verifier
code_challenge_methodstringYesEncoding algorithm that transforms code_verifier into a code_challenge, only 2 methods are supported, S256 and plain
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
  code_challenge=a-code-challenge
  code_challenge_method=S256

​
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_typestringYesauthorization_code
codestringYesThe authorization code received
redirect_uristringYesMust match the authorization request
client_idstringYesYour OAuth client ID
code_verifierstringYesA randomly generated string used to verify the client request on the server
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 "code_verifier=your-code-verifier"
Success Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": ""
}
Success Response (with offline_access scope): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": null,
  "scope": "offline_access"
}
FieldDescription
access_tokenJWT access token for API requests
refresh_tokenJWT access token for generating access tokens
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"

​
Step 5: Exchanging the refresh token for an access token

In case of the access token expiring or for rotating the tokens you can pass the refresh token in order to retrieve a new access and refresh token
ParameterTypeRequiredDescription
client_idstringYesYour OAuth client ID
client_secretstringYesYour OAuth client secret
grant_typestringYesrefresh_token
refresh_tokenstringYesA jwt used for authentication and access token generation
curl -X POST “https://customerDomain.ambersearch.de/api/oauth/token”
-H “Content-Type: application/x-www-form-urlencoded”
-d “client_id=client_id”
-d “client_secret”=“client_secret”
-d “grant_type=refresh_token”
-d “refresh_token=your-refresh-token” Success Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
}
Success Response (with offline_access scope): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": null,
}

​
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
  • Rotate access tokens regularly if not using offline_access
  • Switch between the code_verifier strings constantly
  • Never expose tokens in URLs or logs