Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

With the following querystring parameters:

Querystring Parameter

Description

username

email

persistentUID

Exactly one of these parameters must be included to identify the account.

returnUrl

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.

...

  • The OpenAthens account username
  • The unique email address associated with the account – that is, i.e. the ‘uniqueEmailAddress’ attribute is , if set.
  • The persistent user ID (PUID) for the account.

...

application/vnd.eduserv.iam.auth.transferToken-v1+json object

Object field

Description

username

The account username

expiry

The time at which the given token expires

sessionInitiatorUrl

The location to which the user should be redirected to establish the session

Response codes

HTTP Response Code

Description

200

The token was generated

400

The request was invalid

403

Forbidden

404

The account could not be found

Info
iconfalse

The user should be redirected to the URL specified by ‘sessionInitiatorUrl’. The format of the URL that is returned may change so calling applications must not alter or infer the structure of this URL in any way.

For very recently created accounts, following a ‘sessionInitiatorUrl’ may result in an error. This is due to a slight delay while new accounts become active on the authentication service. This should only occur if an application programmatically creates or activates an account and then immediately creates a ‘sessionInitiatorUrl’ for that account.

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.

Status
Description
SuccessThe OpenAthens session was established successfully.
TokenExpiredThe session initiator token in the request has expired (tokens are valid for 60 seconds after they are issued).
SessionFailureThe OpenAthens system was unable to establish the session (non-specfic error).

Example

Code Block
Request:
GET /api/v1/example.org/organisation/123456/account/session?username=<username>&returnUrl=<returnUrl> HTTP/1.1
Authorization: OAApiKey <api-key>
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.auth.transferToken-v1+json
{


   "username" : "example_username",
   "expiry" : "2013-08-20T15:48:00Z",
   "sessionInitiatorUrl" : "https://login.openathens.net/account/sso?
token=FGdsghjytj6y54y46J54yrthTR45yersdfhewkjfhwjkfhejkhfwjkfhjkfhewjkfhfkwjefwe",
   "links": [
   {
      "username" : "example_username",
      "href" : "/api/v1/example.org/account/example_account",
      "rel" : "self",
      "type" : "application/vnd.eduserv.iam.account-v1+json",
      "method" : "get",
   }
 ]}

 


See also:

Children Display
depth1
pageOpenAthens REST API documentation