This section provides some more detailed example showing how the API may be used in a number of common scenarios.
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 '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:
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:
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:
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:
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:
- 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