Authentication and access

Use an API key for a server-to-server integration. Send it with every request in the x-api-key header.

Get an API key#

You do not need to administer the server to build an integration. Ask your server administrator for the connection details and a key. You can copy this request and send it through your normal support channel:

Text

I would like to try the 2c8 API. Please provide:
- Our API base URL (including /mt-backend/api/v1) and any VPN requirements.
- An application API key, shared through an approved secure channel.
- A repository and model name I can recognize in the results.
- Whether this is a test or production installation.
I will begin with the read-only quickstart.

The token used to sign in to server configuration is not the application API key. Once you have the key, follow the quickstart. Do not request a "read-only key": this release's application keys are not restricted to the read-only operations in the tutorial.

For administrators: create and securely share a key

Create a key in server configuration#

A server administrator creates the key in the server configuration application:

Open your server's configuration application at https://your-server.example/MTServer-WEB/. If prompted to Login with token, use its 2c8 Portal link to obtain a login token for that server, paste it in the Token field, and choose Next. You must authenticate as a server administrator.
Open API keys in the navigation. The direct route is /MTServer-WEB/api-keys on that server.
Choose Create API Key, enter an application name, and set an expiry date.
Create the key and copy the generated value into your integration's secret store. Save it at creation time; the list does not reveal the secret again.

If you do not have administrator access, ask your administrator to create and securely provide the key. The token used to sign in to server configuration is not the application API key.

Send the key#

HTTP request

GET /mt-backend/api/v1/repositories?projection=SIMPLE HTTP/1.1
Host: your-server.example
x-api-key: YOUR_API_KEY

Use HTTPS. Store keys in a secret manager or protected environment configuration. Do not include them in frontend JavaScript, source control, logs, or support messages.

Understand application access#

An API key identifies an application, not the administrator who created it. In this release, application access is broad: repository membership checks and the normal model, symbol, and document read/write permission filtering are bypassed for application requests.

Do not assume a key is restricted to one repository or is read-only. Keep it in a trusted integration and control what that integration exposes to its users.

Application authentication does not grant the administrator role. In particular, the API-key management endpoints require administrator authentication; an application key cannot create or manage other keys. Endpoint-specific validation and resource constraints still apply.

Manage a key#

Administrators can view key metadata and use the configuration application's actions to Suspend, Activate a suspended key, Revoke, or Delete a key. Expired keys are not valid for new authentication.

For rotation, create a replacement, update your integration, verify a read-only request, and then revoke the previous key.

Suspension, revocation and deletion add the key to a blocklist checked before cached authentication. Expiry is different: successful authentication is cached for up to five minutes, so an expired key may continue to authenticate until that cached result expires. Administrators operating several backend instances should verify key status across their deployment; this guide does not promise instant propagation between instances.

Reference: API-key management. These are administrative operations, not part of the quickstart.

Authentication versus authorization#

Response	What to check
`401 Unauthorized`	Is the header present? Is this a key for the correct server? Is it active and unexpired?
`403 Forbidden`	Does this operation permit application authentication, or does it require an administrator? Are there additional access constraints?

Repeatedly retrying the same credentials will not resolve these failures. For other responses, see Troubleshooting.