Authentication

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:

Client Redirects User to Authorization Endpoint

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

User Authentication

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

Authorization Code Issued

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

Exchange Code for Access Token

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

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:

Parameter	Type	Required	Description
`response_type`	string	Yes	Must be `code`
`client_id`	string	Yes	Your OAuth client ID
`redirect_uri`	string	Yes	Must match one of the registered redirect URIs
`scope`	string	No	Space-separated list of requested scopes
`state`	string	Recommended	Opaque value for CSRF protection
`code_challenge`	string	Yes	Encoded version of the code verifier
`code_challenge_method`	string	Yes	Encoding 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

Parameter	Description
`code`	The authorization code (valid for 10 minutes)
`state`	The 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):

Parameter	Type	Required	Description
`grant_type`	string	Yes	`authorization_code`
`code`	string	Yes	The authorization code received
`redirect_uri`	string	Yes	Must match the authorization request
`client_id`	string	Yes	Your OAuth client ID
`code_verifier`	string	Yes	A 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"
}

Field	Description
`access_token`	JWT access token for API requests
`refresh_token`	JWT access token for generating access tokens
`token_type`	Always `Bearer`
`expires_in`	Token lifetime in seconds (3600 = 1 hour, null = permanent)
`scope`	Granted 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

Parameter	Type	Required	Description
`client_id`	string	Yes	Your OAuth client ID
`client_secret`	string	Yes	Your OAuth client secret
`grant_type`	string	Yes	`refresh_token`
`refresh_token`	string	Yes	A 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

Scope	Description
`offline_access`	Request 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:

Error	Description
`invalid_request`	The request is missing a required parameter or is malformed
`unauthorized_client`	The client is not authorized to use this flow
`access_denied`	The user denied the authorization request
`invalid_grant`	The authorization code is invalid or expired
`invalid_client`	Client 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

API Documentation

Endpoints

OpenAI-like Endpoints

AmberSearch MCP Server

Indexing API

Overview

Base URL

OAuth 2.0 Flow

Getting Started

Discovery Endpoints

Authorization Endpoint

Step 1: Redirect User to Authorization

Step 2: User Authentication

Step 3: Authorization Response

Token Endpoint

Step 4: Exchange Authorization Code for Access Token

Using the Access Token

Step 5: Exchanging the refresh token for an access token

Scopes

Error Handling

Security Best Practices

​Overview

​Base URL

​OAuth 2.0 Flow

​Getting Started

​Discovery Endpoints

​Authorization Endpoint

​Step 1: Redirect User to Authorization

​Step 2: User Authentication

​Step 3: Authorization Response

​Token Endpoint

​Step 4: Exchange Authorization Code for Access Token

​Using the Access Token

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

​Scopes

​Error Handling

​Security Best Practices

Overview

Base URL

OAuth 2.0 Flow

Getting Started

Discovery Endpoints

Authorization Endpoint

Step 1: Redirect User to Authorization

Step 2: User Authentication

Step 3: Authorization Response

Token Endpoint

Step 4: Exchange Authorization Code for Access Token

Using the Access Token

Step 5: Exchanging the refresh token for an access token

Scopes

Error Handling

Security Best Practices