HTTP API Authentication

Audience: Data Owners and Data Users

Content Summary: Most calls to the HTTP API require authentication. All requests must include a valid token in the Authorization HTTP header in order to be considered an authenticated request. In order to obtain a bearer token, users must first authenticate with Immuta using an enabled authentication method. This token should be used for multiple requests until it expires. Once a token expires, users must authenticate again to get a new token. When a request uses an expired token, the request will return with a 401 status code.

This page includes the API key authentication endpoint, request and response parameters, and example requests and responses for API authentication.

Example Authenticated Request

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/rpc/user/current

API Key Authentication Endpoint

The recommended way to authenticate with the service is to use the user API keys, which users can generate on the API Keys tab on their profile page. These API keys allow for a more secure form of authentication, as users can generate and revoke keys at will. They also offer a more simple approach since only one piece of information (the API key) is required for the request.

Request Parameters

• apikey (string): API Key
  • Example: "0123456789abcdefghijkl"

Example Request Payload:

{
    "apikey": "0123456789abcdefghijkl"
}

Example Request:

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data @example_payload.json \
    ${IMMUTA_URL}/bim/apikey/authenticate

immuta_url=""
echo -n "API Key: "
read -s apikey
echo
curl -X POST \
${immuta_url}/bim/apikey/authenticate \
--header 'Content-Type: application/json' \
--data "{\"apikey\":\"${apikey}\"}"

import requests

def authenticate_apikey(immuta_url, apikey):
    """Authenticate API Key
    Authenticate a user against the Immuta API using an API key

    - immuta_url: Base URL for the Immuta instance
    - apikey: API Key
    """
    payload = {
        "apikey": apikey,
        }
    urlfmt = "{}/bim/apikey/authenticate"
    url = urlfmt.format(immuta_url)
    response = requests.request("POST", url, json=payload)
    return response.json()

Response Parameters

• authenticated (boolean): Indicates if the authentication was successful.
  • Example: true
• token (string): Temporary authentication token
  • Example: "0123456789abcdefghijkl"

Example Response:

{
  "authenticated": true,
  "token": "2d798e67a4214e2960ca4b"
}

User/Password Authentication Endpoint

In order to authenticate users with their username and password, you can use the IAM specific authenticate endpoint.

Request Path Parameters

• iamid (string): The IAM system the user authenticates with.

Request Parameters

• username (string): Username.
  • Example: "user@domain"

Example Request Payload:

{
    "username": "user@domain",
    "password": "<redacted>",
}

Example Request:

immuta_url=""
iamid="bim"
echo -n "Username: "
read username
echo
echo -n "Password: "
read -s password
echo
curl -X POST \
${immuta_url}/bim/iam/${iamid}/user/authenticate \
--header 'Content-Type: application/json' \
--data "{\"username\":\"${username}\",\"password\":\"${password}\"}"

import requests

def authenticate_user(immuta_url, username, password, iamid="bim"):
    """Authenticate user
    Authenticate a user against the Immuta API using Username and Password

    - immuta_url: Base URL for the Immuta instance
    - iamid: IAM System ID user logs in with
    - username: Username
    - username: Password
    """
    payload = {
        "username": username,
        "password": password,
        }
    urlfmt = "{}/bim/iam/{}/user/authenticate"
    url = urlfmt.format(immuta_url, iamid)
    response = requests.request("POST", url, json=payload)
    return response.json()

Response Parameters

• authenticated (boolean): Indicates if the authentication was successful.
  • Example: true
• token (string): Temporary authentication token.
  • Example: "2d798e67a4214e2960ca4b"
• tokenExpiration (string): Timestamp indicating when the token expires.
  • Example: "2018-11-02T20:00:43.687Z"

Error Response

This endpoint returns status code 401 in the event of failed authentication.

• message (string): Reason for error.
  • Example: "Authentication failed for user"
• error (string): Error text.
  • Example: "Unauthorized"
• statusCode (int): Error status code.
  • Example: 401

Example Response:

{
  "authenticated": true,
  "token": "2d798e67a4214e2960ca4b",
  "tokenExpiration": "2018-11-02T20:00:43.687Z"

}