Authentication

Most API calls require authentication. Access is controlled through OAUTH2 with JSON web tokens.

For security reasons, it is recommended that a separate user account be created for scripting API access. This account should have the minimum permissions necessary to perform its duties.

API access is controlled via OAUTH2 with JSON web tokens. In order to authenticate, the client script first obtains an access token using a username/password and optionally, a refresh token:

--> POST /api/mgmt.aaa/1.0/token
{
  "user_credentials": {
      "username": "<name>",
      "password": "<password>"
  },
  "generate_refresh_token": true
}
<-- 201
{
  "access_token": <access_token>,
  "refresh_token": <refresh_token>
  "expires_at": 900,
  "token_type": "bearer"
}

All subsequent API requests must include an Authorization header containing the access token. Note that the “B” in “Bearer” must be capitalized:

Authorization: Bearer <access_token>

For example:

--> GET /api/npm.reports.sources/1.0/items/aggregates
Authorization: Bearer eyJhbGciOiJIUzI1NiIs..QzWXcXNrz0ogtVhfEd2o
<-- 200 OK
{...}

Access tokens expire after 15 minutes. Attempting to use an expired access token will result in 401/Unauthorized responses.

To obtain a new token, either resubmit a username/password request, as documented earlier, or use the refresh token instead:

--> POST /api/mgmt.aaa/1.0/token
{
  "refresh_token": <refresh_token>
}
<-- 200 OK
{
  "access_token": <access_token>,
  "expires_in": 900,
  "token_type": "bearer"
}

Using refresh tokens is recommended, as they are more secure. When a script finishes, it should log out and revoke its refresh token, rendering it unusable by a third party. Additionally, if a refresh token is not used within 60 minutes, it will automatically be expired by the system.

A maximum of 25 refresh tokens may be active per user at once. If a 26th token is requested, the oldest granted token will be revoked immediately.

Logging Out

Logging out revokes the refresh token. If you are not using refresh tokens, then no special logout procedure is necessary. Access tokens are not tracked, and will naturally expire within 15 minutes.

Revoking refresh tokens is not strictly required, but is recommended for security. While refresh tokens will also expire automatically, they do so based on activity and not after a fixed time.

To revoke a refresh token:

--> POST /api/mgmt.aaa/1.0/refresh_tokens/revoke
{
  "refresh_token": <refresh_token>
}
<-- 200 OK