Skip to main content

Authentication

Ahmed Boghdady
Updated

Authentication

Authentication to the API is performed via two types:

HTTP Basic auth

To use the HTTP Basic auth, provide your username and password. A JSON Web Token (JWT) should be returned in Set-Cookie header to be used for API authentication.

Copy 
curl -X 'POST' \
  'https://us-api.mobilecommons.com/auth/api/login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: O2IfcwRVXQ1IVQU0H0c5cGczLw4adhEuPRt8jcjU037_WqvA6PJHr4KT' \
  -d '{
  "username": "jdoe@mobilecommons.com",
  "password": "johndoe"
}'

The JWT will be automatically set in your cookies to authenticate your APIs.

API Docs: POST /auth/api/login

API key auth

To use the API key auth, create a new API key and a secret pair, which you will then use to authenticate your requests. This is suitable for service clients that you would not want tied to a particular employee’s identity or ability to authenticate.

Creating a key and secret pair

First, create your key and secret pair via the api_keys resource, providing the company_id you want to associate the key with:

Copy 
curl --location --request POST 'https://us-api.mobilecommons.com/api/v3/api_keys?company_id=acda1ded-1139-47ec-9743-98399b391289' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

This will return a key and a secret pair that you can use to authenticate your requests:

Copy 
{
  "company_id": "acda1ded-1139-47ec-9743-98399b391289",
  "company_name": "My Company",
  "description": null,
  "disabled_at": null,
  "id": "e3ac4cb5-5131-41dc-9cae-f40b5e767ebd",
  "inserted_at": "2022-04-01T11:42:59Z",
  "key": "e102ddf9-99dd-4437-a367-c5908c2715f3",
  "secret": "d714001b-ea85-4308-a075-0e7474be391e",
  "status": "Active",
  "updated_at": "2022-04-01T11:42:59Z"
}

You can document your key and secret pairs via a description field in a request JSON body or update it later via PUT6

Note: The key and secret pair will be hashed after it's generated, so be sure to store a copy in a secure location. .

API Docs: POST /api/v3/api_keys

Listing your key and secret pairs

If you want to get all your keys and secret pairs, you can have the api_keys list all keys for your user:

Copy 
curl --location --request GET 'https://us-api.mobilecommons.com/api/v3/api_keys' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

API Docs: GET /api/v3/api_keys

Authenticating using key and secret pairs

To authenticate using key and secret pairs, via HTTPS only, use the Authorization header per request, with the Basic authentication scheme (as described in RFC 7617).

The value attached should be the result of taking the key and secret joined with a colon, as in {Key}:{Secret} and base64-encoding it into a single token, as:

Authorization: Basic {Base64Encode({Key}:{Secret})}

The request can be made in following way:

Copy 
curl --location 'https://us-api.mobilecommons.com/umm/api/programs?page=1&page_size=10' \
--header 'Authorization: Basic ***** \
--header 'Cookie: authly=true'