Versions Compared

Key

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

...

Where id is the organisation ID and type is the type of account being created, usually 'personal'
(personal, organisation_administrator, user_administrator, self_registration, access).

Request querystring

The following querystring parameters affect the behaviour of the operation.

Querystring Parameter

Description

sendEmail

A Boolean indicating whether to send an email to the user. The email sent will be an activation email if the account status is set to ‘pending’ or a new account email containing the account credentials if the status is set to ‘Active’ and a password is supplied.

defaultPermissions

A Boolean indicating whether to assign all the default permission sets to this account upon creation. This is mutually exclusive with the ‘permissionSets’ field in the account request object. If ‘permissionSets’ is set in the request, this flag must be omitted.

Response payload

The response payload is the application/vnd.eduserv.iam.account-v1+json object that was created. This includes the allocated object ID, activation code (if status was set to ‘pending’) and permission sets (if applicable).

The ‘Location’ header contains a reference to the newly created account object.

Response codes

HTTP Response Code

Description

201

The account was created.

400

The request was invalid.

application/vnd.eduserv.iam.admin.accountRequest-v1+json object

...

When modifying existing accounts, only the fields that the client wishes to modify need be sent (see the account management section for further details).

Object field

Description

status

The activation status of the account. May be one of:

  • active
  • pending

activationCodeExpiry

The expiry for activation codes generated as part of this request (only applies if status = Pending).

groups

An array of group names of which the account is a member. Currently only one group can be specified.

permissionSets

A list of permission set names for this account.

expiry

The expiry date for this account. Expiry dates cannot be set more than 5 years in the future.

username

The username for the account. This only applies on account creation.

attributes

An object that maps attribute names to values (object key = field name, value = message). The available attribute names are available by querying the account schema.

password

The account password in clear-text. Passwords are stored in OpenAthens in one-way hashed form. Hence, they are not subsequently retrievable via an account object.

ipRanges

An array of IP address ranges from which the account will be restricted. Only applies when creating administration or access accounts.

organisationMove

This is used to move the account to a different parent organisation (see section 9.5). This only applies on account modification.

Account status

The status of the account designates whether it is ‘active’, or ‘pending activation’. Accounts marked as active have had a password assigned to them, either by an administrator, or as part of the account activation process. Active accounts may be used to access OpenAthens-protected resources until the account expiry date is reached. Pending accounts cannot login to resources or the API until a password is assigned to the account and the account status is changed to ‘active’.

The following table summarises the valid values for the account status.

Account status

Description

pending

The account requires activation by the user. If an account is created or changed to this status, an activation code will be automatically generated for the account. If the ‘sendEmail’ querystring parameter is set, an activation email will be sent to the user. An account cannot authenticate if it is in this state.

active

The account is active and may be used to authenticate by the user. If an account is created with this status and the ‘sendEmail’ querystring parameter is set, a new account email, containing the password, will be sent to the user.

Error handling

If an invalid account creation or modification request is sent an HTTP status of 400 will be returned. The response body will contain an application/vnd.eduserv.iam.admin.accountError-v1+json object detailing the reasons why the request failed.

application/vnd.eduserv.iam.admin.accountError-v1+json object

Object field

Description

message

A description of the error.

invalidFields

An object mapping request field to error messages (object key == field name, value == message).

invalidAttributes

An object mapping user attributes to error messages (object key == attribute name, value == message).

8.1.5.     Example

Code Block
Request:
POST /api/v1/example.org/organisation/12345/accounts/create/personal?sendEmail=true&defaultPermissions=true HTTP/1.1
Content-Type: application/vnd.eduserv.iam.admin.accountRequest-v1+json
Authorization: OAApiKey <api-key>


{
    "expiry": "2017-01-01T00:00:00Z",
    "status": "pending",
    "username": "expuser01",
    "attributes": {
        "forenames": "first",
        "surname": "last",
        "emailAddress": "first.last@example.com"
    },
    "groups" : [
                  "group1",
                  "group2"
    ]
}
Response (success):
HTTP/1.1 201 Created
Location: /api/v1/example.org/account/1012345
Content-Type: application/vnd.eduserv.iam.account-v1+json


{
    "id" : "1012345",
    "status" : "Pending",
    "activationCode" : {
      "code": "ABC123DEF",
      "expires": "2017-01-01T00:00:00Z",
    }
    "attributes" : {
                  "username" : "expuser01",
                  "forenames": "first",
                  "surname": "last",
                  "emailAddress" : "first.last@example.org"
              },
    "groups" : ["group1"],
    "permissionSets" : [
               { "id": "5678",
                 "name": "exp#default"
                 "href": "/api/v1/example.org/permissionSet/5678"
               }
    ],
    "organisation" : { "id" : "1234",
                 "href" : "/api/v1/example.org/organisation/1234"
                },
    "links" : [
               { "rel" : "self",
                 "type" : "application/vnd.eduserv.iam.account-v1+json",
                 "href" : "/api/v1/example.org/account/1012345",
                 "method" : "get",
               },
               { "rel" : "parent",
                 "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
                 "href" : "/api/v1/example.org/organisation/1234",
                 "method" : "get"
               },
               { "rel" : "delete",
                 "href" : "/api/v1/example.org/account/1012345",
                 "method" : "delete",
               },
               { "rel" : "update",
                 "type" : "application/vnd.eduserv.iam.admin.accountRequest-v1+json",
                 "href" : "/api/v1/example.org/account/1012345/modify",
                 "method" : "post",
               },
               { "rel" : "child",
                 "type" : " application/vnd.eduserv.iam.serviceList-v1+json",
                 "href" : "/api/v1/example.org/account/1012345/services",
                 "method" : "get",
               }
    ]
}
Response (error):
HTTP/1.1 400 Bad Request
Content-Type: application/vnd.eduserv.iam.admin.accountError-v1+json


{
    "message" : "One or more supplied fields are invalid",
    "invalidFields" : {
                  "username" : "This username is already in use"
    }
    "invalidAttributes" : {
                  "emailAddress" : "This is not a valid email address"
              }
}

...

The response payload is an application/vnd.eduserv.iam.account-v1+json object.

Response codes

HTTP Response Code

Description

200

The request was successful.

204

The request was successful but returned no content

404

Account does not exist with the given id.

403

Administrator does not have permission to view this account.

Example

Code Block
Request:
GET /api/v1/example.org/account/1234567 HTTP/1.1
Authorization: OAApiKey <api-key>
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.account-v1+json


{
    "id" : "1234a67",
    "status" : "Active",
    "organisation" : {  "id" : "676573453",
                        "defer" : { "id": "6585674434353",
                                    "date" : "2012-11-22T13:24.345Z"   
                                     }          
    },
    "attributes" : {
      "username" : "expjohn",
      "emailAddress" : "john@example.org"
    },
    "memberOf": [ {
                   "href" : " /api/v1/example.org/group/234567",
                   "name" : "group1"
    } ],
    "links": {
     ... detail omitted
    },
}

...

This type represents account objects, together with metadata about their group membership, and organisation affiliation.

Object field

Description

id

The unique account identifier.

status

The activation status of the account. May be one of

  • active
  • pending

type

The type of account. May be one of

  • personal
  • organisation_administrator
  • user_administrator
  • self_registration
  • access

activationCode

The activation code for the account (if status = ‘pending’). This is an object with code and expires properties. These carry the code, and the associated expiry date, respectively.

created

The date on which the account was created.

modified

The date on which the account was last modified.

expiry

The date on which the account expires.

organisation

The identifier of the parent organization of the account (see the following section).

memberOf

An array of groups to which the account is a member.

permissionSets

A list of permission sets for this account.

attributes

An object that maps attribute names to values (object key = field name, value = message).

administersOrganisations

An array of organisations that this account administers (applies to administration accounts only).

Organisation field

The ‘organisation’ field in the response contains an object with the following parameters.

Object field

Description

id

The id of the new organisation (required).

name

The display name of the organisation.

defer

An object containing id and date parameters which specify a deferred move (see section below).

Modifying individual accounts

...

The following querystring parameters affect the behaviour of the operation.

Querystring Parameter

Description

sendEmail

A Boolean value indicating whether to send an email to the user. The email sent will be an activation email if the account status is set to ‘Pending’ or a modified account email containing the account credentials if the status is set to ‘Active’ and a password is supplied.

defaultPermissions

A Boolean value indicating whether to assign all the default permission sets to this account.

Request payload

This should be an application/vnd.eduserv.iam.admin.accountRequest-v1+json object.

Response codes

HTTP Response Code

Description

200

The request was successful.

404

An account does not exist with the given id.

400

The request was invalid. The response should be an error indicating the reason.

Example

Code Block
Request:
POST /api/v1/example.org/account/1234567/modify HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: application/vnd.eduserv.iam.admin.accountRequest-v1+json


{
  "attributes" : {
    "forenames" : "john",
    "emailAddress" : "john@example.org"
  }
}
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.account-v1+json


... detail omitted

...

The ‘organisation’ field in the request must be an object with the following parameters.

Object parameter

Description

id

The id of the new organisation (required).

Example

Code Block
Request:
POST /api/v1/example.org/account/12345/modify HTTP/1.1
Authorization: OAApiKey <api-key>

Content-Type: application/vnd.eduserv.iam.admin.accountRequest-v1+json

{
  "organisation": {
    "id" : "67575664534"
  }
}

Response:
HTTP/1.1 204 OK
Content-Type: application/vnd.eduserv.iam.account-v1+json 

...

Where PUID is the persistent user identifier for the account.

Response codes

Response code

Description

204

The request was successful the user was emailed

400

The request is invalid, most commonly the user identifier is an invalid format

404

The username and or email cannot be matched on AP.

Example

Code Block
json
json
Request:
GET /api/v1/example.org/account/passwordreset/abcd1234:456789a HTTP/1.1
Authorization: OAApiKey <api-key>

Response:
HTTP/1.1 204 No Content
Content-Type: application/vnd.eduserv.iam.account-v1+json

...


See also:

Children Display
depth1
pageOpenAthens REST API documentation