Access Tokens

Provision an access token

Provisions a new access token. Either bind it to an account, or set permissions - an instance-wide token that is not narrowed reaches every account and every endpoint, so the API declines to mint one. A token can not mint one less restricted than itself: when the calling token has an address allowlist, a referrer allowlist, a rate limit or an expiry, the request has to repeat each of them at least as narrowly (addresses within its allowlist, referrers from its list, a rate no higher, an expiry no later), otherwise it is refused with 403.

post/v1/tokens

Request

  • Base URL: https://your-emailengine-host
  • URL: https://your-emailengine-host/v1/tokens
  • Auth: HTTP bearer

Headers

x-ee-timeoutinteger

Request timeout in milliseconds. Raises the command timeout above the EENGINE_TIMEOUT default for a long-running request; a value below the default has no effect

Example:30000

Request body

accountstring

Bind the token to one account. Omit for an instance-wide token, which then has to set permissions

descriptionstring required

Token description

scopesTokenScope[] required

Token permission scopes: "api" for REST API access, "smtp" for SMTP submission, "imap-proxy" for IMAP proxy authentication, "mcp-manage" for the instance management tools of the MCP endpoint, "mcp" for its mail tools

metadatastring

Related metadata in JSON format

expiresstring date-time

Optional time when this token stops working. Omit for a token that never expires

ipstring

IP address of the requester

Example request

{
  "account": "user123",
  "description": "Token description",
  "metadata": "{\"example\": \"value\"}",
  "restrictions": {
    "referrers": [
      "*web.domain.org/*",
      "*.domain.org/*",
      "https://domain.org/*"
    ],
    "addresses": [
      "1.2.3.4",
      "5.6.7.8",
      "127.0.0.0/8"
    ],
    "rateLimit": {
      "maxRequests": 20,
      "timeWindow": 2
    }
  },
  "permissions": {
    "actions": [
      "read"
    ],
    "groups": [
      "message",
      "mailbox"
    ]
  },
  "expires": "2021-02-17T14:43:18.860Z",
  "ip": "127.0.0.1"
}

Response

Returns the new token value. This is the only time it is shown - store it now.

tokenstring required

The access token. This is the only time it is returned - store it now

idstring required

Identifier for this token, as reported by the token listings

Example response

{
  "token": "9a6d24f8f43e01b1f2c4f11a5c5b8e51fe0a4e0eda06e1be5b8d6cc2c66b95dc",
  "id": "1bc12baf7f0d5e51fe0a4e0eda06e1be5b8d6cc2c66b95dc0fbe4d2e9f5d5e1a"
}

Changes

No recorded changes to this operation across all 1 revision of this API.