--- canonical: https://amplience.com/developers/docs/apis/asset-management/overview/usage/ title: Usage description: How to authenticate and make requests to the Amplience GraphQL Management API endpoint, including obtaining OAuth2 access tokens. audience: Developer date_published: 2022-06-23 date_modified: 2024-07-02 --- # Usage ## API Endpoint There is a single endpoint for all requests to the GraphQL Management API: https://api.amplience.net/graphql ## Authentication ### Credentials Amplience uses [OAuth2](https://oauth.net/2/) to authorize access to the GraphQL Management API. To use the API you will need an API key and secret. These credentials will be provided to you by Amplience at the beginning of your project, or you can request them from Amplience support. Your API key will define the resources to which you have access. Your API key and secret are used to obtain an access token from the Amplience authorization service. This token must be included in the authorization header of all requests to the GraphQL Management API and is set to expire after a set time period, generally 300 seconds. You can also use a [personal access token](https://amplience.com/developers/docs/apis/authorization/personal-access-tokens) instead of a token generated from an API key and secret to use the account management features of the API. Note that for experimentation purposes, you can log in to the [API Playground](https://api.amplience.net/graphql) which will provide an authenticated call to the API #### Getting an access token ​ To get an authorization token, send a `POST` request to the Amplience authorization server at https://auth.amplience.net as follows. ​ #### Request ``` POST https://auth.amplience.net/oauth/token ``` ##### Auth Headers | Header | Description | | -------------- | ----------------------------------- | | `Content-Type` | `application/x-www-form-urlencoded` | ##### Auth Parameters The parameters should be URL encoded and included in the body of the request: ``` client_id={yourclientid}&client_secret={yoursecret}&grant_type=client_credentials ``` Replace `{yourclientid}` and `{yoursecret}` with your client id and secret. ​ | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `client_id` | The client id (API key) provided to you by Amplience | | `client_secret` | The client secret provided to you by Amplience | | `grant_type` | Set this to `client_credentials` to specify that the authorization token should be generated based on the client ID and secret | #### Response ##### Auth Status codes | Status code | Description | | ----------- | ----------------------------------------------- | | `200` | OK. Credentials are valid. | | `400` | Bad Request. client id or secret are not valid. | ##### Auth Response body If the `client_id` and `client_secret` are valid, the response body will be returned as in the example below. Note that the example `access_token` has been truncated. ```json { "access_token": "eyJraWQiOiJhbXBsaWVuY2UtdG9rZW4tc2lnbmluZy1rZXkiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJhbXBsaWVuY2iwiZXhwIjoxNTU…", "session_expires_in": 0, "expires_in": 300 } ``` ​ You will need to save the access token and include it in requests to the API. If the token has expired, request another token from the authorization service. ### Including the token in an API request ​ To make a request to the GraphQL Management API, you would send a request to API endpoint: ​ ``` POST https://api.amplience.net/graphql ``` ​ In the request header you must set the `Authorization` format to `Bearer` and include the `access_token`: ​ ``` Authorization : Bearer {access_token} ``` ​ Replace `access_token` with the access token returned by the authorization service. ​ ​ If the access token is valid, then the request is processed and the response is returned. ​ ## Methods Both `POST` and `GET` methods are supported. The HTTPS `POST` method is recommended. The query should be sent in the body of a `POST` request. The HTTPS `GET` method requires that the query is included in the URL string using the `?query=` parameter. ## Status codes | Status code | Phrase | Description | | ----------- | --------------------- | ------------------------------------------------------------------------------------- | | `200` | OK | Successful request | | `400` | Bad Request | Non specific error with request. Usually due to an invalid query or mutation argument | | `429` | Too many requests | A rate limit has been exceeded | | `500` | Internal server error | Non specific error occurred on the server | ## Error response format If `400` (Bad request) error occurs, the response body contains a JSON object containing an errors array. This will contain the error type, a message field describing the error and a locations array stating where in the request body the error was found. Here is an example of an error due to a mistyped query: ```json { "errors": [ { "message": "Cannot query field \"mimetype\" on type \"Asset\". Did you mean \"mimeType\"?", "locations": [ { "line": 5, "column": 7 } ], "extensions": { "code": "GRAPHQL_VALIDATION_FAILED" } } ] } ``` ## Asset ingestion Assets can be ingested using the `createAsset` mutation by specifying a URL path to the source asset. The source asset must be available via a publicly accessible URL. ### Identifying ingestion requests Ingestion requests from the GraphQL Management API can be identified by the user agent, which is sent in an HTTP request header: | Request header name | Request header value | | ------------------- | ------------------------- | | `User-Agent` | `amplience-dam-api/1.5.0` | Note: The number suffixed to the header value is the current version number of the API, and this number is subject to change.