Authenticating to the API

API URIs

API URIs have the following prefixs:

https://admin.openathens.net/api/v1/<domain-id> (read and write, e.g. only for account management)

https://login.openathens.net/api/v1/<domain-id> (read only, and high availability e.g. for user authentications, password resets, etc)

Where domain-id is the unique ID for the OpenAthens domain.

Authentication

All access to the API is authenticated. Authentication is used to

control programmatic-access to the API from applications (such as an administration or registration UI).
verify the credentials of accounts in the system, for instance to provide a login form.

The API supports the following methods of authentication:

HTTP Basic Authentication, as described in RFC 2617, for authenticating user accounts
API key authentication, using a long-lived key previously allocated by the web console, for administrator functions. For account management you will need the 'Full access' permission set on the key

Prerequisites

In order to authenticate to the API, you must

know the name of a valid OpenAthens domain.
have an API client that is capable of connecting to an HTTPS URL, sending and receiving JSON objects.
have the credentials of a user account within the OpenAthens domain or have a previously assigned API key for administrator functions.

HTTP Basic Authentication

Basic auth can no longer be used for administrator functions due to the multi-factor authentication requirement - you will need an API key (See API keys)

Basic authentication can be used to verify the credentials for an account (these would probably have been collected via a login form).

For authenticating end-users, see the API usage examples section.

Authentication errors

Failed authentication will result in an HTTP 401 status from the API. Additional failure information is returned in the response body. This is encoded as an application/vnd.eduserv.iam.authenticationError-v1+json object.

application/vnd.eduserv.iam.authenticationError-v1+json object

This object is used to encode information about a failed authentication attempt.

Object field

Description

reason

A code indicating the reason for the authentication failure. This may be one of

‘badCredentials’ – The supplied credentials were invalid. This means the username or password were invalid (for basic authentication) or the API key was invalid (for API key authentication).
‘accountExpired’ – The account to which the credentials apply has expired.
‘invalidIP’ – The supplied credentials cannot be used from the IP address that the client is connecting from. This applies to access accounts only.
'InvalidIPDeferred' - Failed multi-factor authentication. This applies to administrator accounts

message

A human-readable message describing the failure. This may be used on a UI to provide a reason for the failure to the user.

API Key Authentication

API keys long-lived authentication tokens that are associated with an OpenAthens domain or sub-organisation. They have exactly the same hierarchy permissions and restrictions as the organisation where they were created. They have an expiry date measured in years rather than minutes. Long-lived keys are intended for applications to use to authenticate against the API. This decouples an application from the account credentials and means if the administrator changes their password, the application won’t need to be updated to send the new value.

To obtain a long-lived key, you should log into the OpenAthens administration site (https://admin.openathens.net) as the administrator you wish to request a key for. Under ‘Management’, select ‘API keys’ and create a new key with the relevant permission. See: API keys

Authorisation

All operations will only be performed within the scope of the organisation where it was created - e.g. the key of an organisation will only be able to administer accounts belonging to that organisation, or sub-organisations. Authenticating with an end-user (non-administrator) account will only provide very restricted access to API functions.

Any request that is not authorised will fail with an HTTP 403 status code.