Endpoints

Our API endpoints are all exported on https://api.alcmeon.com/ and documented in our Reference documentation.

Applications

Alcméon Applications define the credentials and permissions required to access Alcméon APIs.

Once created, an Application provides:

• A client secret to be used for authentication.
• Permissions that scope which API endpoints the application is allowed to access.

Authentication

Alcméon APIs support two authentication mechanisms:

Basic Authentication

When using HTTP Basic Authentication, clients must include their Instance ID and Application Secret as credentials in the Authorization header of each request:

Authorization: Basic <base64(InstanceID:ApplicationSecret)>

This method is simple and does not require token management.

👉

Instance ID

Your Instance ID can be found in the Alcméon url of your environment: https://alcmeon.com/c/v3/#/{InstanceID}/...

Bearer Token (OAuth 2.0 – Client Credentials Grant)

Alcméon now supports OAuth 2.0 with the client credentials grant flow. This method provides improved security and token expiration handling is required.

How it works:
To obtain an access token, make a POST request with Basic Authentication credentials in the header (same as above), and the following JSON body:

POST /v1/oauth2/token
{  
    "grant_type": "client_credentials"
    "client_id": "<InstanceId>",
    "client_secret": "<ApplicationSecret>"
}

A successful response will contain a Bearer token valid for one hour:

{  
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",  
  "token_type": "Bearer",  
  "expires_in": 3600,
  "expires_at": "2025-04-29T15:26:22.671957+00:00"
}

Then use the token in the Authorization header of any API call:

Authorization: Bearer <access_token>

For instance:

curl -X GET https://api.alcmeon.com/teams \
  -H "Authorization: Bearer <access_token>"

Replace <access_token> with the value you received from the token request.

👉

Permissions

Access to specific API endpoints will depend on the permissions granted to the associated Application, as for the Basic Authentication method.

👉

Token Expiration

When the token expires, simply repeat the POST /v1/oauth2/token request to retrieve a new one.

Rate Limiting

Alcméon APIs implement rate limiting measured in requests per minute to ensure fair usage and system stability. When a rate limit is exceeded, the API will return a 429 Too Many Requests response with the following structure:

{
    "error": "rate-limit-reached",
    "details": {
        "rate_limited_until": "2025-04-29T15:26:22Z"
    }
}

The rate_limited_until field in the details object contains the UTC timestamp when the rate limit will reset and you can resume making requests.

Webhooks

A number of our APIs are based on the use of webhooks which must be exposed by our customers and will be invoked by our infrastructure.

Traffic filtering

All requests sent to these endpoints will originate from the FQDN outbound.alcmeon.com. It is important to respect the TTL associated with this DNS entry (300 seconds) to avoid any disruption that might be caused by dynamic changes in the topology of our infratructure.

Starting on March 1st 2022, we will enforce a new traffic routing policy for outbound traffic.

Signature verification

Outgoing requests contain the custom header X-Alcmeon-Webhook-Signature. These signatures are calculated as a SHA256 HMAC on the concatenation of the request path and request body using the application secret as key. The result is hexadecimal encoded and stored in the signature header.

The python code below illustrates how this signature can be re-calculated for an example of webhook url https://api.alcmeon.com/demo/subbot/start?key=value:

import hmac, hashlib, binascii
application_secret = b'88c29fe9d5477643'  # as displayed in your Alcmeon application configuration
path = b'/demo/subbot/start'  # your webhook endpoint path
body = b'the bytes of the http request body you received'
signature = hmac.new(
    application_secret,
    msg=path + b' ' + body,
    digestmod=hashlib.sha256
).hexdigest()