API
BlogWebinars
  1. Management API

Management API authentication

The Management API requires you to authenticate before you can make an API request. The following authentication methods are available:

OAuth 2.0 authentication

You can authenticate to the Management API using the OAuth 2.0 client credentials grant.

Note

OAuth 2.0 is the preferred authentication method. Basic authentication is deprecated and will be removed in the future. We recommend using OAuth 2.0 whenever possible.

Overview

This is a machine-to-machine flow designed for server-side integrations where no end-user interaction is involved. The following diagram provides an overview of how the authentication works.

sequenceDiagram
    participant C as Your integration
    participant A as ecosio Authorisation Server
    participant M as Management API

    C->>A: POST /oauth2/token<br/>(client_id + client_secret)
    A-->>C: { access_token, expires_in }

    C->>C: Cache the token.<br/>Reuse it until it expires.

    C->>M: GET /api/v1/management/...<br/>Authorization: Bearer <token><br/>X-APP-KEY: <app_key>
    M-->>C: 200 OK

In practice, the flow works as follows:

  1. Obtain a short-lived access token from the ecosio authorisation server using your client ID and client secret.
  2. Cache the token so that you can use it for all requests until it expires.
  3. Send the token as a Bearer token along with your app key in each Management API request.
  4. When the token expires, repeat the steps to obtain a new token.

We recommend that you reuse a token for all Management API requests until it expires. Generating a new token for each request is not a good practice and can result in an HTTP 429 Too Many Requests response.

Prerequisites

Before you can obtain an access token, you must:

Obtain an access token

To obtain an access token, make a POST request to the ecosio authorisation server. You can use basic authentication to provide the client ID as the username and the client secret as the password in the Authorization header. Alternatively, you can provide the client ID and client secret as client_id and client_secret body fields.

In either case, you must set the content type to application/x-www-form-urlencoded and provide the following fields in the request body:

  • grant_type=client_credentials
  • scope=management-api

The following example uses basic authentication.

curl --request POST https://auth.ecosio-hub.com/oauth2/token \
  --header "Authorization: Basic $(echo -n 'your-client-id:your-client-secret' | base64)" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials&scope=management-api"

The following example passes the client ID and client secret in the request body.

curl --request POST https://auth.ecosio-hub.com/oauth2/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials&scope=management-api&client_id=your-client-id&client_secret=your-client-secret"

Note

Making another request returns a new token. It never returns an existing token, even if it has not expired.

If the request is successful, the authorisation server returns an HTTP 200 OK response and a response body that looks like the following example.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "management-api"
}

The following fields are available in the response body.

FieldDescription
access_tokenNewly generated access token. This is an encoded JSON Web Token (JWT).
token_typeType of token. Always set to Bearer.
expires_inNumber of seconds remaining before the token expires. For example, if this is set to 600, the token is valid for 10 minutes.
scopeScope you can use the token for. Set to management-api.

Use the access token in Management API requests

When making a Management API request, include the token in the Authorization header of each request. You must also provide the app key as the value of the X-APP-KEY header field. You obtain the app key from the Monitor.

The following example demonstrates how to use the token to Find companies.

curl --request GET https://api.ecosio-hub.com:443/api/v1/management/companies \
  --header "Authorization: Bearer your-access-token" \
  --header "X-APP-KEY: your-app-key"

The Management API checks whether the token is valid. If the token is missing, expired, or invalid, the API returns an HTTP 401 Unauthorized response.

Each token expires after a short time, for example, after 10 minutes. You can find out when a token expires in:

  • The body of the response that returned the token. The expires_in field stores the number of seconds before the token expires. We recommend using this option.
  • The token itself. The JWT payload has an exp claim that contains the expiration time as a Unix timestamp, in seconds. You can decode the JWT payload to access this information.

After a token expires, you must obtain a new one.

In addition to token validation, the Management API uses the identity embedded in the token to determine which records your integration is permitted to access. Your credentials are tied to your company's Management API connector, and the API ensures that you can only read and write data that belongs to your own company.

Basic authentication

Warning

OAuth 2.0 is the preferred authentication method. Basic authentication is deprecated and will be removed in the future. We recommend using OAuth 2.0 whenever possible.

You can authenticate to the Management API using basic authentication. When making a request, provide the following:

  • Your user ID as the username in the Authorization header.
  • Your user key as the password in the Authorization header.
  • The app key as the value of the X-APP-KEY header field.

You obtain these values in the Monitor.

The following example demonstrates how to use the credentials to Find companies.

curl --request GET \
  --url https://api.ecosio-hub.com:443/api/v1/management/companies \
  --header "X-APP-KEY: your-app-key" \
  --header "Authorization: Basic $(echo -n 'your-user-id:your-user-key' | base64)"

Updated 14 days ago

What’s Next

Did this page help you?

Updated 14 days ago

What’s Next

Did this page help you?