Authentication

OAuth 2.0

Mambo uses the OAuth 2.0 industry-standard protocol for API authorization. There are numerous client libraries and samples available which work with our OAuth 2.0 implementation. The official OAuth site has a code page with libraries for many different languages.

Client credentials flow

The Mambo API uses specifically the OAuth 2.0 Client Credentials grant flow. This does not require user intervention as the authentication will be provided by your public and private API keys.

Prerequisites: obtaining your API keys

Before starting, you will need your public and private API keys which can be found in the administration panel.

Implementation steps

The client credentials OAuth 2.0 flow requires two steps:

1. Request Access Token: First a call must be made to the /oauth/token API endpoint. This request must have a query parameter specifying the grant_type property as client_credentials and a Basic Authentication header with the public and private keys.

2. API Requests using the Access Token: Once we have the token from step 1, we simply add a Bearer Authentication header with the token for each request. If the token expires, we will receive an error and a new access token can be requested following step 1 above.

Example implementation

The example below uses Curl to retrieve and use an access token.

Make sure you replace YOUR_PUBLIC_KEY, YOUR_PRIVATE_KEY and YOUR_DOMAIN_URL with the relevant values.

Requesting an access token

Bash

curl -X POST -u YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=client_credentials"
  https://YOUR_DOMAIN_URL/oauth/token

Sample response:

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "token_type": "Bearer",
  "expires_in": 43199
}

Making authenticated API requests

Use the access token to make an API request:

Bash

curl -X GET
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
  https://YOUR_DOMAIN_URL/api/v1/sites

Troubleshooting

• If you receive a 401 Unauthorized error, your access token may have expired. Request a new token and retry.
• Ensure both public and private keys are correctly entered in the Basic Authentication header.
• Verify that your API keys have the appropriate permissions for the endpoints you're accessing.

---

Related topics

• API keys