Authentication

Every API request authenticates with an API key sent as a bearer token. A key belongs to the person who created it and acts as that person, limited to the scopes you choose for the key.

Who can create keysCopy Anchor Link

Creating, editing and revoking keys needs the MANAGE_API_KEYS permission. In a new workspace only the Administrator role has it. An administrator can add it to another role in Settings → Roles & Permissions.

Keys are managed in the product only. An API key cannot create, edit or revoke API keys: such a request answers 403 with the code API_KEY_CANNOT_MANAGE_KEYS.

Create an API keyCopy Anchor Link

APROS keeps only a hash of the key, so nobody can show it to you again. If you lose a key, revoke it and create a new one.

Keys start with sk-. The keys table shows each key's Key Prefix (its first ten characters, for example sk-3f9a1c2...), so you can tell keys apart without seeing the secret.

Send the keyCopy Anchor Link

Put the key in the Authorization header of every request:

Authorization: Bearer sk-...

Keep the key in an environment variable rather than in your code. The examples on this site read it from APROS_API_KEY. This call returns what the key is allowed to do:

curl https://<your-workspace>.apros.app/api/me/scopes \
  -H "Authorization: Bearer $APROS_API_KEY"

A request with no key, an unknown key, a revoked key or an expired key answers 401:

{ "error": "No authentication token found", "code": "AUTHENTICATION_ERROR" }

Scopes and permissionsCopy Anchor Link

A scope is the name of a permission in your workspace, in the form ACTION_RESOURCE: VIEW_LEAD, CREATE_LEAD, UPDATE_INVOICE and so on. The same permissions make up the roles in Settings → Roles & Permissions.

A key can do only what both of these allow:

• The key's scopes. A scoped key can use only the permissions on its list. An unrestricted key is not limited by a list.
• Its owner's rights. The key acts as the person who created it, so it never gets more than that person has. A scope the owner does not hold has no effect, and if the owner loses a permission, their keys lose it too. Row-level access applies as well: a key sees only the records its owner's role lets them see (their own, their department's, or all).

If the owner's account is suspended or terminated, their keys stop working and every request answers 403 with the code ACCOUNT_DISABLED.

Common scopes:

Each operation in the API reference lists the permissions its path enforces in x-apros-scopes. The list is kept per path, not per method: GET and DELETE on the same path share one list, and a read needs only the read permission from it.

Each custom entity type you create gets its own permissions, named after the type, and you can scope a key to them like any other permission. GET /api/me/scopes lists them.

Check what a key can doCopy Anchor Link

GET /api/me/scopes describes the credential you call it with. Any valid key can call it, whatever its scopes.

{
  "credential": {
    "type": "api-key",
    "id": "0f6b2c1e-7d4a-4b8e-9c3f-2a1d5e6f7a8b",
    "name": "Website forms",
    "keyPrefix": "sk-3f9a1c2..."
  },
  "granted": { "mode": "list", "scopes": ["CREATE_LEAD", "VIEW_LEAD"] },
  "userPermissions": ["CREATE_LEAD", "DELETE_LEAD", "UPDATE_LEAD", "VIEW_LEAD"],
  "effective": ["CREATE_LEAD", "VIEW_LEAD"],
  "catalogue": [
    { "name": "CREATE_LEAD", "source": "endpoint", "endpoints": ["/api/leads"] }
  ]
}

The arrays are shortened here. The fields:

Change a key's name or scopesCopy Anchor Link

The secret does not change, so integrations that use the key keep working with the new rights. Every change to a key's scopes is recorded in the workspace's audit log, with the scopes before and after. A revoked key cannot be edited.

Rotate a keyCopy Anchor Link

There is no rotate button. Rotate a key by replacing it:

To rotate on a schedule, give keys an expiry in Expires in (days). An expired key answers 401 like a revoked one.

Revoke a keyCopy Anchor Link

Revoking cannot be undone. From its next request the key answers 401, and the table shows it as Revoked. The revocation is recorded in the audit log.

Keep keys safeCopy Anchor Link

• Call the API from your server. Never put a key in browser code, a mobile app or a public repository.
• Use one key per integration, so you can revoke one without breaking the others.
• Give each key only the scopes it needs, and an expiry when you can.