The API provides a method to generate an OpenAthens authentication token for a given account.
Generating a new token
To generate a new token, a client application must
- authenticate to the API as described in Authenticating to the API. You should use the read-only 'https://login.openathens.net/api/v1/...' address.
Perform a GET request to the following URL:
With the following querystring parameters:
Exactly one of these parameters must be included to identify the account.
The URL that the user will be returned to after the session has been established. This will usually be a link to a page in the application making the request, e.g. a resource catalogue
The request must also be accompanied with a ‘returnUrl’ parameter.
Accounts are identified using one of the following three unique identifiers:
- The OpenAthens account username
- The unique email address associated with the account – i.e. the ‘uniqueEmailAddress’ attribute, if set.
- The persistent user ID (PUID) for the account.
To generate a token for an individual account based on username perform a GET request to:
To generate a token for an individual account based on email address perform a GET request to:
To generate a token for an individual account based on PUID perform a GET request to:
The response payload is an
The account username
The time at which the given token expires
The location to which the user should be redirected to establish the session
HTTP Response Code
The token was generated
The request was invalid
The account could not be found
When the user is passed to the
returnUrl, it will contain an additional
status parameter to indicate whether the request was successful. This may optionally be used by the calling application to take action depending on whether the operation was successful or otherwise. Aside from token expiry though, there are almost no reasons why a failure would occur.
|Success||The OpenAthens session was established successfully.|
|TokenExpired||The session initiator token in the request has expired (tokens are valid for 60 seconds after they are issued).|
|SessionFailure||The OpenAthens system was unable to establish the session (non-specfic error).|
- API overview
- Authenticating to the API
- API entry-point
- Fetching attribute schemas via the API
- Fetching organisations via the API
- Fetching Groups via the API
- Account management via the API
- API bulk operations
- Fetching available service providers via the API
- Generating authentication tokens for end-users via the API
- API usage examples