Searching...
API Overview
This section describes the API functionality in the AMM.
API access can be accessed via HTTP(if enabled) and HTTPS from the AMM ip address. It is recommended to use HTTPS. All data is sent and received as JSON.
If the AMM deployment supports unsecured HTTP, and the API is accessed via unsecured HTTP, then the network should allow OAuth access token as plain text in the HTTP request header, or else the access token could be filtered out from the unsecured HTTP request. The AMM API endpoints would then return an unauthorized error response.
HTTP Verbs
Where possible, API strives to use appropriate HTTP verbs for each action.
- GET
- Used for retrieving resources.
- POST
- Used for creating resources, or performing custom actions.
Authentication
The AMM uses OAuth 2.0 to provide authorized access to its API. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a user by orchestrating an approval interaction between the user and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
The post Oauth2 Simplified explains very well the main concepts of this framework.
When a user grants access to an API Client, an Access Token is issued to access user's data using AMM APIs. This token has a limited lifetime of 24 hours. A Refresh Token has a lifetime of 30 days and once used, cannot be reused. A new Refresh Token is issued when the Access Token is refreshed.
There are different ways to request an access token:To request access, an API Client MUST be registered in AMM.
Request an Access Token using the Resource Owner Flow
In this flow the end-user credentials (i.e. username and password) are used directly as an authorization grant to obtain an access token.
The client MUST use the HTTP POST method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters.
Request
POST https://ip address of AMM/api/oauth/token?grant_type=password&username=userid&password=pwd
Response
An access token is returned by the authorization server when your application is successfully authenticated:
{
"access_token": "56caf660-fdb7-49ff-91b5-6b1918e5738e",
"token_type": "bearer",
"refresh_token": "c2a9d770-bca9-453f-9482-b2cfe80e7319",
"expires_in": 3431,
"scope": "READ WRITE"
}
In addition to the access token, the response contains the number of seconds before the token expires and a refresh token.
The client MUST send its API client credentials when making requests to the token endpoint. See Authenticating an API client.
Bad credentials from the end-user will return error Invalid Grant.
| Name | Description | Use | Default | Type |
|---|---|---|---|---|
| grant_type | Value MUST be set to "password" | required | string | |
| username | The username. Remote user format can be used. | required | string | |
| password | The password | required | string |
| HTTP Status | Name | Description |
|---|---|---|
| 401 | unauthorized | Authentication failed |
| 403 | access_denied | API access is disabled for API client, user or customer group |
| 408 | api.request.timeout | Raised when response took longer than configured request timeout threshold. Default is 300 seconds |
Request an Access Token using the Implicit Flow
The implicit flow is a simplified authorization code flow. It is optimized for clients implemented in a browser using a scripting language. Instead of issuing an authorization code, the access token is sent directly to the redirect URI as a fragment of the request.
Before directing the user back to the client with the access token, AMM authenticates the user and obtains authorization.
As this flow reduces the number of round trips to obtain an access token, only one request is needed.
/api/oauth/authorize
Request
GET https://ip address of AMM/api/oauth/authorize?response_type=token&grant_type=implicit&client_id=4e7ff462b61645d38296eff2fbbf70ad&redirect_uri=https://ip address of redirect server/authentication/callback
Response
AMM authenticates the user and ask for authorization.
When the client application obtains authorization from the user, it is redirected to the provided callback URI.
https://ip address of redirect server/authentication/callback#access_token=f797967c-7788-4d8d-8169-f043bc7f395b&token_type=bearer&expires_in=22448&scope=READ%20WRITE
| Name | Description | Use | Default | Type |
|---|---|---|---|---|
| response_type | Value MUST be set to "token" | required | string | |
| grant type | Value MUST be set to "implicit" | required | string | |
| client_id | The client id | required | string | |
| redirect_uri | The URI MUST be an absolute URI and MUST NOT include a fragment component. | required | string |
| HTTP Status | Name | Description |
|---|---|---|
| 401 | unauthorized | Authentication failed |
| 403 | access_denied | API access is disabled for API client, user or customer group |
| 408 | api.request.timeout | Raised when response took longer than configured request timeout threshold. Default is 300 seconds |
Request an Access Token using the Authorization Code Flow
In this flow, the client application needs to obtain an authorization code before requesting an access token.
Instead of requesting authorization using the end-user credentials, the client redirects the user to AMM, which in turn directs the user back to the client with the authorization code.
Before directing the user back to the client with the authorization code, AMM authenticates the user and obtains authorization.
1. Request an authorization code
/api/oauth/authorize
Request
GET https://ip address of AMM/api/oauth/authorize?grant_type=authorization_code&response_type=code&redirect_uri=https://ip address of redirect server/authentication/callback&client_id=8ecea09578ce4e7eb332ba275339b2fe
Response
AMM authenticates the user and asks for authorization.
When the client application obtains authorization from the user, it is redirected to the provided redirect URI with the authorization code.
https://ip address of redirect server/authentication/callback?code=nwllY5
| Name | Description | Use | Default | Type |
|---|---|---|---|---|
| response_type | Value MUST be set to "code" | required | string | |
| grant_type | Value MUST be set to "authorization_code" | required | string | |
| client_id | The client id | required | string | |
| client_secret | The client secret | required | string | |
| redirect_uri | The URI MUST be an absolute URI and MUST NOT include a fragment component. | optional | string | |
| HTTP Status | Name | Description |
|---|---|---|
| 401 | unauthorized | Authentication failed |
| 403 | access_denied | API access is disabled for API client, user or customer group |
| 408 | api.request.timeout | Raised when response took longer than configured request timeout threshold. Default is 300 seconds |
2. Request token
Once the authorization code in hand, it is possible to request an access token.
The client MUST use the HTTP POST method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters.
The client MUST send its API client credentials when making requests to the token endpoint. See Authenticating an API client.
/api/oauth/token
Request
POST https://ip address of AMM/api/oauth/token?grant_type=authorization_code&code=nwllY5&redirect_uri=https://ip address of redirect server/authentication/callback
Response
If your application is successfully authenticated, the authorization server will return the access token:
{
"access_token": "8e3c8725-38e4-4b35-8d0f-eac1ee1a0e1c",
"token_type": "bearer",
"refresh_token": "f3303c26-7f71-4372-a5dc-175ae50d0b20",
"expires_in": 83860,
"scope": "READ WRITE"
}
In addition to the access token, the response contains the number of seconds before the token expires and a refresh token.
Refresh Access Tokens
When a client acquires an access token, the client also receives a refresh token. From AMM 2.17.2, refresh tokens can no longer be re-used, once consumed.
The client has to make a refresh request to the token endpoint by adding the right parameters.
Refresh tokens are valid for 30 days. When the client does a refresh request, the actual refresh token is consumed and a new refresh token will be issued for the new access token.
The client MUST use the HTTP POST method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters.
Also, the client MUST send its API client credentials when making requests to the token endpoint. See Authenticating an API client.
/api/oauth/token
Request
POST https://ip address of AMM/api/oauth/token?grant_type=refresh_token&refresh_token=f3303c26-7f71-4372-a5dc-175ae50d0b20
Response
If your application is successfully authenticated, the previously valid refresh token is consumed and a new one is issued:
{
"access_token": "854dbdcd-e89e-49c3-b9a3-cb842bae35a5",
"token_type": "bearer",
"refresh_token": "5ed08175-0680-47e2-a08c-71cb65803b19",
"expires_in": 86399,
"scope": "READ WRITE"
}
In addition to the access token, the response contains the number of seconds before the token expires and a new refresh token. The old refresh token is consumed and is no longer valid.
The refresh token is regenerated on every refresh request.
An invalid refresh token will be denied access with an http status 400 Bad Request with the error message Invalid refresh token.
| Name | Description | Use | Default | Type |
|---|---|---|---|---|
| grant_type | Value MUST be set to "refresh_token" | required | string | |
| refresh_token | The refresh token sent by the authorization server when it authenticates the client and validates the authorization grant | required | string |
| HTTP Status | Name | Description |
|---|---|---|
| 400 | invalid_grant | Invalid refresh token |
| 401 | unauthorized | Authentication failed |
| 403 | access_denied | API access is disabled for API client, user or customer group |
| 408 | api.request.timeout | Raised when response took longer than configured request timeout threshold. Default is 300 seconds |
Authenticating an API client
API Clients MUST authenticate with the AMM when making requests to the token endpoint. Client credentials (client_id/client_secret are issued when the API Client is registered in the AMM.)
It is highly recommended to use the HTTP Basic Authentication Scheme [RFC2617] to authenticate API clients with the AMM.
E.g. The user agent wishes to send the client_id "my_client" and the client_secret "the_secret". First, it will create the credentials by separating the client_id and the client_secret by a single colon (:).
my_client:the_secret
The resulting string has to be Base64 encoded (mostly all programming languages have libraries to do that. Or use an online encoder for testing).
bXlfY2xpZW50OnRoZV9zZWNyZXQ=
The basic credentials are built like this.
Basic bXlfY2xpZW50OnRoZV9zZWNyZXQ=
Finally, the basic credentials are set into the Authorization HTTP header.
POST https://ip address of AMM/api/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlfY2xpZW50OnRoZV9zZWNyZXQ=
grant_type=authorization_code&code=1JV6zV&
Expire Access Tokens
The client can only revoke an access token issued to itself. If a refresh token was issued together with the access token, then both access token and refresh token will be revoked at the same time.
/api/oauth/expire
Request
POST https://ip address of AMM/api/oauth/expire?access_token=cd35b9c1-3f2a-45fb-91e5-4fdea9879136
Response
If the token is valid, it will be revoked and a 200 http status response is returned. If a 401 is returned, then the token is not valid.
| Name | Description | Use | Type |
|---|---|---|---|
| access_token | The token to expire | required | string |
| HTTP Status | Name | Description |
|---|---|---|
| 401 | unauthorized | Authentication failed |
| 403 | access_denied | API access is disabled for API client, user or customer group |
| 429 | too_many_requests | Request has reached rate limit |
| 408 | api.request.timeout | Raised when response took longer than configured request timeout threshold. Default is 300 seconds |
Operations
Get
In 2.17.1 only GET is available to query the AMM database. To see a list of available GET commands, refer to API Get Commands.
Administration
API Client Management
To add and delete API clients available on the AMM, see API Client Management.
API Access Management
When an API client is created, it is by default set to enabled for the customer group selected. API access can be disabled at either the API client level, customer group level, or at the AMM user level. See API Access Control for more information.
Usage Control
To ensure that AMM resources are not exhausted, the number of API requests from a customer group can be limited. See API Usage Control for more information.
Usage Monitoring
To monitor API usage, see API Usage Monitoring.