Administration · Setup & configuration · 6 min read

API keys for integrations

Create, limit, rotate and revoke bearer keys that let another system call a2NSoft.

Before you begin

An API key lets another system, such as a web shop, call a2NSoft without a person signing in. A key always belongs to an integration user, never to a person.

• Create the integration user first on Administration > Users > System users. Choose the user type API, Integration or Service, and no employee. See Create a system user.
• The API keys screen is for company administrators. You need member.manage.

Create a key

1. Go to Administration > Users > API keys and click New key.
2. Type Name (what uses it), up to 120 characters, for example Shopify sync. Empty gives 'Name the key after what uses it.'
3. Choose the Integration user. Only API, Integration and Service users are listed. A person is refused: 'A key belongs to an integration user (type API, integration or service), never a person.'
4. Under Limited to permissions, type the permission codes the key may use, separated by commas or spaces, for example partner.view, document.view. An unknown code gives 'Unknown permission: abc.xyz'. The key can never do more than its integration user's roles allow.
5. Set Ends on. The default is 90 days from today. The date must be after today and within 366 days: 'A key ends after today and within 366 days.'
6. Click Create.

Copy the secret now

The full key is shown once, with a Copy button. Afterwards the list shows only the Starts with prefix. If you lose the key, rotate it.

Use the key

The other system sends the header Authorization: Bearer <key> on each request. A request that needs a permission the key does not carry is refused. A key cannot reach another company's data. A key also cannot manage keys: 'Keys are managed by a person, not by another key.'

Rotate a key

1. Find the active key and click Rotate.
2. Copy the new key, shown once.

The old key keeps working for 7 days so you can change the other system without a gap, then stops.

Revoke a key

1. Click Revoke on the key.
2. Type Why. It is required: 'Say why the key is revoked.'
3. Confirm.

The status becomes Revoked, the next request with that key is refused, and a revoked key cannot be rotated. The list also shows Last used, Limited to and Ends, which helps you spot keys nobody uses.

What happens next

Key creation, rotation and revocation are written to the audit trail. A key past its end date stops working without further action.

Good to know

• Integration users cannot sign in at the login page ('This is an integration account. It cannot sign in here.').
• Give each integration its own key and the smallest permission list that works.
• Revoke the key the day an integration is retired; do not wait for the end date.