API

Endpoints

The API is accessible at the following endpoint: https://api.breign.eu.

For sensitive use-cases, you may want to contact your support representative for a custom on-premise deployment of the Breign platform.

Authentication

To request the Breign API, you need an API Key or an access token for your account. You can generate a new API Key on the Breign web app under your profile.

All request are authenticated by adding a x-api-key header with the account's API Key. The API Key grants access to all ressources (agents, applications, organizations...) accessible to the user it was generated for.

API auth flow

You can also generate a new API or a token Key by performing the following request:

POST {{endpoint}}/auth/code
Body :
{
    "email": "your.email@example.com",
    "type": "api_key" or "jwt"
}
Response :
{
    "id": "cff0505b-a78c-4723-baf0-42ebcc2f72f0"
}

A unique code is sent to the mailbox if the account exists. Verify the code with the following request (using the id returned in the previous request):

POST {{endpoint}}/auth/code/:codeId/verifications
Body :
{
    "code": "09HD74KM"
}
Response :
{
    "secret": "ai-98747777HDHAHZFJzad8746D"
}
or
{
    "token": "ey...."
}

Tokens expire in 1 hour after their generation. API keys does not expire but can be removed from your account in your settings.

Verifying tokens

Should you verify the validity of a token (signature), you can retrieve the public keys used to sign the JWT at the standard well-known URL:

GET https://api.breign.eu/.well-known/jwks.json
Response
{"keys":[{"crv":"Ed25519","x":"jHvgGLn-OtR36ahB8hcTiCw1f6jtuwwSidhNr0juZo4","kty":"OKP","alg":"Ed25519"}]}

Specifications

We do publish a openapi generated typescript client, you can install it via

npm install --save @breign/client

Inside the installed package is an openapi.json file.

While you can call the endpoints specified directly using any HTTP request library, we recommend you use the client functions as much as possible as those are properly typed and kept up to date.