---
updatedAt: 2026-08-06T09:23:36.000Z
agentTools:
  projectIndex: https://developers.alcmeon.com/llms.txt
---

# Custom identification

Exchange a jwt token that contains secret per-user authentication information with a jwt that can be used for all other API endpoint invocations. The jwt is valid for 7 days.

The input jwt token should be encrypted with the HS256 JWT algorithm and the secret key obtained from support@alcmeon.com. This JWT token should contain the following custom claims:

  - `customer_id` - A string that uniquely identifies the underlying customer account.
  - `sms_notification_phone_number` - If specified, a string that contains a phone 
    number (with +XXX international prefix) to which sms notifications should be 
    sent whenever a human sends a reply to this customer
  - `name` - A string which contains the customer's name to display in the Alcméon user profile
  - `attributes` - A list of key/value string pairs: If specified, a set of key/value metadata 
    fields which will be associated with the customer and displayed on the user profile page 
    in Alcméon. Example: [["age", "24"], ["City", "Paris"]]


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "https://inmessage.alcmeon.com/prod/api"
    }
  ],
  "info": {
    "title": "InMessage",
    "version": "1.0"
  },
  "x-readme": {
    "explorer-enabled": false
  },
  "components": {
    "parameters": {
      "page_id": {
        "in": "path",
        "name": "page_id",
        "schema": {
          "type": "string"
        },
        "required": true,
        "description": "ID of the page. This is not an integer."
      }
    },
    "schemas": {
      "RateLimitResponseError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Rate limit reached"
          },
          "details": {
            "type": "string",
            "description": "A string showing the time when the rate limit will be reset. Example: {'rate_limited_until': '2024-01-22T13:05:41Z'}\n"
          }
        }
      },
      "AuthenticatedPage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The `page_id`"
          },
          "name": {
            "type": "string",
            "description": "A human-friendly name associated with the `page_id`"
          },
          "icon_url": {
            "type": "string",
            "format": "uri",
            "description": "Brand icon url associated with the `page_id`"
          },
          "override_default_chat_window_css": {
            "type": "string",
            "description": "Css for styling the chat window."
          },
          "privacy_link": {
            "type": "string",
            "format": "uri",
            "description": "The url for the privacy notice"
          },
          "lang_code": {
            "type": "string",
            "description": "Default lang code for page, eg \"en\", \"fr\". Used by InMessage client to  localize messages if it does not know any better default.\n"
          },
          "persistent_menu": {
            "$ref": "#/components/schemas/PersistentMenu"
          },
          "jwt": {
            "type": "string",
            "description": "A JSON Web Token which can be used to identify the user in further  http requests in the Authorization header\n"
          }
        }
      },
      "PersistentMenu": {
        "description": "A list of menu items",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "alcmeon_restart_conversation",
                "web_url",
                "postback"
              ]
            },
            "title": {
              "type": "string",
              "description": "The label of the menu item"
            },
            "urlOrPayload": {
              "type": "string",
              "description": "if type is `web_url`, the URL to open in a new tab when  the user clicks on this item; if type is `postback`, the  metadata to post in a postback message when the user clicks on this item.\n"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "inmessage_authentication_jwt": {
        "description": "This is the authentication mecanism to authenticate calls to the  [Authenticate](#get-/-page_id-/authenticate) endpoint\n",
        "type": "http",
        "scheme": "bearer"
      },
      "inmessage_authentication": {
        "description": "This is the authentication mecanism to authenticate most calls to the [InMessage API]() endpoints.\n",
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "inmessage_authentication": []
    }
  ],
  "paths": {
    "/{page_id}/authenticate": {
      "get": {
        "security": [
          {
            "inmessage_authentication_jwt": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/page_id"
          }
        ],
        "tags": [
          "Authenticate"
        ],
        "summary": "Custom identification",
        "description": "Exchange a jwt token that contains secret per-user authentication information with a jwt that can be used for all other API endpoint invocations. The jwt is valid for 7 days.\n\nThe input jwt token should be encrypted with the HS256 JWT algorithm and the secret key obtained from support@alcmeon.com. This JWT token should contain the following custom claims:\n\n  - `customer_id` - A string that uniquely identifies the underlying customer account.\n  - `sms_notification_phone_number` - If specified, a string that contains a phone \n    number (with +XXX international prefix) to which sms notifications should be \n    sent whenever a human sends a reply to this customer\n  - `name` - A string which contains the customer's name to display in the Alcméon user profile\n  - `attributes` - A list of key/value string pairs: If specified, a set of key/value metadata \n    fields which will be associated with the customer and displayed on the user profile page \n    in Alcméon. Example: [[\"age\", \"24\"], [\"City\", \"Paris\"]]\n",
        "responses": {
          "200": {
            "description": "returned upon success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticatedPage"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached. Default limit is set to 15 requests per minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitResponseError"
                }
              }
            }
          }
        }
      }
    }
  }
}
```