API usage examples

This section provides some more detailed example showing how the API may be used in a number of common scenarios.

Authenticating accounts

Authenticating users using the API requires a client to perform an API request, sending the credentials of the user as an HTTP Basic authentication header. These credentials consist of the unique username of the account and the account password.

Authenticating via a username or email address

Authenticating an account where the username or email address is known to the client (e.g. a user has entered it in a login form) is simple. The client simply needs to encode the username and password as a standard HTTP Basic authentication header and send this to the read-only 'https://login.openathens.net/api/v1/...' entry point. Use GET for anything other than an administration account.

On success, the client should not expect a body in the response, as per Authenticating to the API. E.g:

CODE

Request:
 
GET /api/v1/example.org/ HTTP/1.1
Authorization: Basic c3VwZXI6YWJjMTIz
 
Response (success):
 
HTTP/1.1 204 No Content

This will return a 20x status on successful authentication and a 401 
if the credentials are not correct (including if the account does not exist). 
On failure a more detailed error may be returned via a 
application/vnd.eduserv.iam.authenticationError-v1+json object.

Response (error):
 
HTTP/1.1 401 Unauthorized
Content-Type: application/vnd.eduserv.iam.authenticationError-v1+json; charset=UTF-8
 
{
  "code" : "accountExpired",
  "message" : "Your account has expired."
}

Creating new accounts

To create a new account the client application must know the organisation under which the account should be created. This may be previously known by the client, or the API may be used to query for the organisation, as detailed in section 7.2.

The client must then construct an application/vnd.eduserv.iam.admin.accountRequest-v1+json object ensuring that the minimum required fields are included. See the section on Account management via the API.

The resource that the request is sent to depends on the type of account being created. In most cases this will be a ‘personal’ account, as shown in the example below. The URLs for creating accounts of different types are linked from the application/vnd.eduserv.iam.admin.organisation-v1+json object. E.g:

CODE

Request:

POST /api/v1/example.org/organisation/1234567890/accounts/create/personal?sendEmail=true HTTP/1.1
Content-Type: application/vnd.eduserv.iam.admin.accountRequest-v1+json; charset=UTF-8
Authorization: Basic c3VwZXI6YWJjMTIz

{
    "status": "pending",
    "username": "jo123456",
    "attributes": {
                  "forenames": "Jo",
                  "surname": "Smith",
                  "emailAddress": "jo@example.org",
                  "institution": "example.org"
              },
    "expiry": "2014-11-20T12:34:00Z",
    "memberOf" : [ {
             "href" : "/api/v1/example.org/group/235684",
             "name" : "group1"
      } ]
}

Response (success):

HTTP/1.1 201 Created
Location: /api/v1/example.org/account/1234567890
Content-Type: application/vnd.eduserv.iam.account-v1+json; charset=UTF-8

{
    "id": "1234567890",
    "status": "Pending",


 ... detail omitted
}

Errors are returned as an application/vnd.eduserv.iam.admin.accountError-v1+json object, containing detail about the field and/or attributes in the request that contained errors. E.g:

CODE

Response (error):

HTTP/1.1 400 Created
Content-Type: application/vnd.eduserv.iam.adminaccountError-v1+json; charset=UTF-8

{
  "invalidFields" : {
    "username" : "Invalid prefix for username: jo123456"
  },
  "invalidAttributes" : { },
  "invalidCreationProperties" : { },
  "message" : "The request was invalid"
}

Moving an account to a new organisation

To update the organisation for a user, perform a POST request to the account modification URL, as detailed in the account management section with the new organisation ID. E.g:

CODE

Request:

POST /api/v1/example.org/account/1234567/update HTTP/1.1
Content-Type: application/vnd.eduserv.iam.admin.accountRequest-v1+json; charset=UTF-8
Authorization: Basic c3VwZXI6YWJjMTIz

{
    "organisation": { "id": "1234567890" }
}

Changing a password on an account

To update the password for a user, perform a POST request to the account modification URL, as detailed in the account management section with the new password in clear-text. E.g:

CODE

Request:

POST /api/v1/example.org/account/1234567/modify HTTP/1.1
Content-Type: application/vnd.eduserv.iam.admin.accountRequest-v1+json; charset=UTF-8
Authorization: Basic c3VwZXI6YWJjMTIz

{
    "password": "rash123"
}