AX1750

Authenticating OData API requests

OData API requests must first be authenticated using an Axiom user name and password. All data requests made using the API will honor the security settings of the specified user.

If you have already logged into Axiom in a browser, you can make OData API requests using URLs typed into that browser. However, this is primarily for testing purposes and not for actual data consumption. When creating a custom web solution using the OData API, you must generate an Axiom key for an Axiom user name and password, and then use that key in an Authorization header for all data requests.

IMPORTANT: User accounts that use SAML and OpenID authentication cannot be used with the OData API. If your system uses these authentication types, you must create a user with a different authentication type for this purpose, such as an Axiom Prompt user.

Generating an Axiom key for an Authorization header

You can use a POST statement to obtain an Axiom key for a specified user name and password. This key can then be used in an Authorization header in subsequent API requests.

To obtain an Axiom key, make a POST request to /svc/authenticate at your Axiom URL. For example:

POST https://mycompany.axiom.cloud/svc/authenticate

The POST request can be sent using either of the following formats:

Format	Requirements
Form encoded	Content-Type: application/x-www-form-urlencoded user=username&password=password
JSON data	Content-Type: application/json; charset=UTF-8 {"user":"username", "password":"password"}

Format

Requirements

Form encoded

Content-Type: application/x-www-form-urlencoded

user=username&password=password

JSON data

Content-Type: application/json; charset=UTF-8

{"user":"username", "password":"password"}

Regardless of the request format, the response uses the following format:

{
	"AxiomKey": "5f83a0277c2a034aa551f03351d92cz2",
	"InstallationName": "Axiom Test System",
	"AxiomVersion": {
		"Major": 2018,
		"Minor": 4,
		"Build": 8,
		"Revision": 87
	}
}

The response includes the requested key, the name of the system, and version information about the system.

Once the key is obtained, it can be used in an Authorization header for subsequent API requests using the following format: AxiomKey <key>. For example:

AxiomKey 5f83a0277c2a034aa551f03351d92cz2

The Axiom key can be used multiple times, but it will expire automatically after about 5 minutes of inactivity. If a key has expired, the request returns a 401 error for invalid credentials. You must then request a new key in order to make data requests.