Skip to content

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. 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.

Method Path Successful Status Code
POST /bim/apikey/authenticate 200

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.

Method Path Successful Status Code
POST /bim/iam/{iamid}/authenticate 200

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"

}