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 a401
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.
Method | Path | Successful Status Code |
---|---|---|
POST | /bim/apikey/authenticate |
200 |
Request Parameters
apikey
(string): API Key- Example:
"0123456789abcdefghijkl"
- Example:
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
- Example:
token
(string): Temporary authentication token- Example:
"0123456789abcdefghijkl"
- Example:
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}/user/authenticate |
200 |
Request Path Parameters
iamid
(string): The IAM system the user authenticates with.
Request Parameters
username
(string): Username.- Example:
"user@domain"
- Example:
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
- Example:
token
(string): Temporary authentication token.- Example:
"2d798e67a4214e2960ca4b"
- Example:
tokenExpiration
(string): Timestamp indicating when the token expires.- Example:
"2018-11-02T20:00:43.687Z"
- Example:
Error Response
This endpoint returns status code 401
in the event of failed authentication.
message
(string): Reason for error.- Example:
"Authentication failed for user"
- Example:
error
(string): Error text.- Example:
"Unauthorized"
- Example:
statusCode
(int): Error status code.- Example:
401
- Example:
Example Response:
{
"authenticated": true,
"token": "2d798e67a4214e2960ca4b",
"tokenExpiration": "2018-11-02T20:00:43.687Z"
}