Authentication

To get a list of projects from the Perforce ALM Server (GET /projects) or get an access token (GET /{projectID}/token), you must use Basic Authentication (username and password) or API Key Authentication (key ID and secret).

We recommend API Key Authentication for more secure authentication because:

• The key and key secret are longer, cryptic strings that are difficult to decode.
• The key can only be used with the REST API. If a key is comprised by a hacker, they cannot use it to log in to ALM clients.
• A user can have multiple keys for different integrations. If a key is compromised, you can delete the key without breaking other integrations.

API key authentication

To use API key authentication:

1. Add a key for the user you want to authenticate with the REST API. You can add keys in the ALM desktop client or Perforce ALM License Server Admin Utility. See Adding API keys.

2. Add the API key and key secret to the request header as api-key:api-key-secret.

GET /perforce-alm/api/v0/4/token HTTP/1.1
Host: localhost:8443
Authorization: ApiKey 293bb9a7…dd36c7:dd487b2fc38e4…bd5ce2f4f

All subsequent requests require using the access token in the header.

Basic authentication

To use basic authentication, the request header must include ALM credentials as username:password. The credentials must be Base64 encoded.

The following example shows a header using the username Administrator and password Password123.

GET /perforce-alm/api/v0/4/token HTTP/1.1
Host: localhost:8443
Authorization: Basic YWRtaW5pc3RyYXRvcjpQYXNzd29yZDEyMw==

All subsequent requests require using the access token in the header.

Access tokens

All requests your application sends to the REST API must include a header that contains an access token, except for getting a list of projects or getting an access token. Access tokens are generated for a project based on a specified ALM username and password and then used for subsequent requests. To generate a token, use the resource.

The token must be included in the request header preceded by Bearer. For example:

GET /perforce-alm/api/v0/4/issues HTTP/1.1
Host: localhost:8443
Authorization: Bearer eyJhbGciOI6IkpXVCJ9.eyJleHAi3Q6jLTQibGljIjoicH

By default, tokens expire in seven days. You can set the number of hours before tokens expire in the Perforce ALM Registry Utility. See the registry utility documentation for information. Tokens are automatically expired when the ALM Server is restarted. The expiresOn parameter in the response contains the date/time the token expires. If an API key is deleted from ALM or the license server, any access tokens created with the key are invalidated and can no longer be used.