API authentication

To support the API, Agile Manager implements a Client Credential flow in OAuth. For more information on the OAuth standard and the Client Credential flow, see The OAuth 2.0 Authorization Framework.

You need an OAuth access token in order to request data from Agile Manager. The access token must be included in the header of each API request.

Note: If you use the API Interactive Help, this token is obtained automatically for your when you log in to the Interactive Help using a pre-generated client ID and secret. For details, see Obtain client details for API access.

Get a token manually

  1. Generate a client ID and secret on the Integrations > API configuration page. For details, see Obtain client details for API access.

  2. Send the client ID and secret to the token endpoint resource, Access Token.

  3. When the current token expires, send the client ID and secret to the Access Token resource again to get a new token.

    Note:  

    • When the token expires, an HTTP 401 (Unauthorized) error occurs, with a message similar to {"error":"invalid_token","error_description":"Access token expired: 164646295_dd3711e9-9619-498e-9a49-66b510d0c01a"}.

    • Sending the client ID and secret before the token expires will not extend the token's lifetime.

Caution: The access token and the client ID and secret used to acquire it should be stored with the same security considerations used to store passwords.

Access token resource

The token resource returns data containing the access token required in the header for other requests in the API.

Access token URI: /agm/oauth/token

This resource is the Authorization Endpoint described in the The OAuth 2.0 Authorization Framework, and can be returned by either a GET operation or POST operation.

The JSON array for each record contains the following fields:

access_token

The token to be passed as the value of the Authorization header in requests to resources in /agm/api/
token_type Generally "bearer"
expires_in Token expiration time in seconds (generally about one hour)
scope

This field is currently not in use.

The scope is always "read trust write"

 
{ 
	"access_token":"777856517_09a705b4-a4b7-4812-98b6-136210de7e4c", 
	"token_type":"bearer", 
	"expires_in":3599, 
	"scope":"read trust write", 
}
GET http://my-server:8080/agm/oauth/token?grant_type=client_credentials HTTP/1.1
Accept: application/json
Authorization: Basic‹b​ase 64 representation of OAuth Client ID:OAuth secret›
POST http://my-server:8080/agm/oauth/token HTTP/1.1
Accept: application/json
Content-Type:application/x-www-form-urlencoded
client_id=‹client ID› & client_secret=‹secret› & grant_type=client_credentials