Alemba API Programmers’ Guide
The RESTful API is built on top of a schema that encompasses the primary data entities in the ASM System.
Last updated
Was this helpful?
The RESTful API is built on top of a schema that encompasses the primary data entities in the ASM System.
Last updated
Was this helpful?
Additionally, a number of logical entities have been added that allow similar entities to be grouped together. The hierarchical structure allows sub-entities to inherit common properties, allowing for consistent meaning and behavior.
The structure is indicated in the Alemba API Entity Details Pane in the API explorer.
The API is platform independent - it can be accessed from any kind of web client, using a range of languages. The API Explorer provides language neutral examples of the structures sent and received as part of a web request/response, for each action, for each entity.
The API uses standard oAuth 2.0 authentication, via /alemba.web/oauth/login.
The authentication workflow issues a short-lived (10 minutes) Access Token and a longer-lived (24 hours) Refresh Token on Login. The Access Token is used for authentication on the REST API. The Refresh Token is used to renew the Access Token and therefore maintain the session. The Refresh Token allocates a ASM Core Session and consumes a licence.
The process is illustrated as follows, flowing from the top downwards.
When the Refresh Token is used to renew an Access Token, a new Refresh Token is also issued, and the ASM Core Session is extended. The used Refresh Token becomes invalid and should be discarded. Clients should store the new Refresh Token for subsequent usage. If the ASM Core Session expires or is removed, the Refresh Token will become invalid. If the Refresh Token expires, the ASM Core Session is terminated.
The single use Refresh Token and short lived Access Token ensures that compromised tokens quickly become invalid - protecting the security of individual users, and preventing unauthorized Access Token reuse.
The Access Token must be presented in the Authorization header of the HTTP request:
Note that the Authorization service supports the following oAuth 2.0 Grant Types:
authorization_code – Authenticate using Single Sign On (SSO), for Windows authentication and SAML
client_credentials – Authenticate using integrated security for anonymous access to the API, not full access
password – Authenticate using a username and password
refresh_token – Authenticate using an existing Refresh Token
Below is an example of the code used to login with a username and password.
For more information on client ids, see Configuring Authentication for the Alemba API.
Or, to refresh your access token:
scope should be set to session-type:Analyst or session-type:User. It is case sensitive.
For successful Logins the response will be:
Note that there is a new refresh_token in the response. The old one will no longer work and must be discarded. It is acceptable to renew your access_token before it is due to expire, but you must not do so with every request.
If the authorization request is not successful, clients can expect to receive a suitable HTTP response code and JSON formatted data containing an error code.
The response data may also include error_description, which gives the developer a clue as to the precise cause of the failure.
In these cases, the response is deliberately vague so as to protect the integrity of the authorization server.
HTTP Status Code
Error Code
Reasons
401
invalid_client
The client_id is incorrect or the client is not enabled
400
invalid_grant
The credentials are not correct, the user is not allowed to login
If you receive a 401 response, it is because your access token has expired, and you must refresh it using the refresh token. If you receive a 401 response when using a refresh token, you must login again with username and password.
You can logout as follows:
Logout will give one of the following responses:
200
Logged out successfully
400
Token invalid or missing
401
Not authorized because it’s not been possible to validate your ownership of the refresh token. In this case you must refresh the access token and try again
403
That refresh token doesn’t belong to you
404
The refresh token is valid but has already been removed. Maybe you logged in elsewhere
The following HTTP verbs are used by the API to perform the listed actions.
Read
GET
Update
PUT
Delete
DELETE
The API supports delete where it is appropriate, including delete for attachments and person images (avatars)
The API can be used to return information about itself, in the form of hypermedia – machine readable descriptions and links to further similar information, allowing a developer to progressively explore the breadth and depth of the API for themselves. What is more, these descriptions are used by the API itself, guaranteeing that this “documentation” is always current.
For example, to discover root level information on the scope of the API, invoke
Note that this response will also be returned for any request which does not specify a resource, for example:
The metadata wi