IDA API Help Page

Introduction

The IDA API provides a means for Operators to generate unique Pseudonymous Keys for Consumers or Devices. A Pseudonymous Key is required when an Operator registers a consumer or device with a Data Engine. Pseudonymous Keys are digitally signed so that Data Engines can validate them to ensure they were generated by IDA and have not been altered.

Types of Credentials

There are two types of credentials for accessing the IDA:

Interactive Credentials provide an Interactive User with access to the IDA website of the purpose of configuring the system.
API Credentials are used to control access to the API methods.

Interactive Credentials

There are four classes of Interactive Users:

Administrators can setup and teardown other interactive users, including other administrators. The Coelition will act as an administrator. An administrator will not manage API Credentials directly.
B2B Generators (Service Providers with Operators) manage a set of API Credentials for themselves and their operators. These API credentials are only usable for generating PseudonymousKeys. There is no need to distinguish between API Credentials used by the Service Provider or the operators and no need to identify the operators.
B2C Generators (Sole Service Providers) manage a single API Credential for their own use. This API Credential is only usable for generating PseudonymousKeys.
Validators (Data Engine Providers) manage a single API Credential for their own use. This credential is only usable for validating PseudonymousKeys.

Interactive users can only have one role and that role cannot be changed once granted. Non-administrator users are not aware of any other users on the system and cannot see any auditing or logging information. They only manage a set of API credentials and their own interactive login. Administrators cannot own API Credentials.

API Credentials

API Credentials have one of the following roles:

Generator: Allowing the userid to generate Pseudonymous Keys
Validator: Allowing the userid to validate Pseudonymous Keys

The role of a API Credential is inherited from the owning Interactive User. For example, a API Credential owned by a B2B Generator will have the role of a Generator.

Authentication and Authorisation

To access the IDA API, callers need API credentials with two components:

A userid to identify the caller.
A password to authenticate the caller.

HTTP basic authentication is used to authenticate calls to the API. Passwords are 64 bytes in length and supplied as a base 64 encoded string. This must be converted to ASCII and prefixed with the userid followed by a colon to form the token. The token then must be converted to base 64 before being passed in as the token for the HTTP Authorisation Header.

If the user identifier is unrecognised, or the wrong password is supplied a HTTP status code 401 ‘invalid username or password’ is returned.

If a request is made by a user which is assigned a role that is not authorised to perform that action, or the user is not authorised by ownership, then the HTTP status code 403 ‘Unauthorised’ is returned.

Status

The Status end-point provides general information about the Identity Authority.

API	Description
GET v2/api/status	Returns the Identity Authority status information.

PseudonymousKey

The PseudonymousKey end-point provides a means to generate pseudonymous keys. It is only accessible to users whose API Credentials have the Generator role.

API	Description
POST v2/api/pseudonymouskey	Generate a new signed Pseudonymous Key for an actor. The mechanism used to sign the response is periodically changed, so the response should be passed to the Data Engine shortly after generation or validation may return false.

PseudonymousKeyBatch

The PseudonymousKeyBatch end-point which provides the means to generate a batch of Pseudonymous Keys in one response packet for users whose API Credentials have the Generator role.

API	Description
POST v2/api/pseudonymouskeybatch	Generate a new signed batch of Pseudonymous Keys. The mechanism used to sign the response is periodically changed, so the response should be passed to the Data Engine shortly after generation or validation may return false.

Validation

The Validation end-point provides the means to validate a signed PseudonymousKey or a signed batch of PseudonymousKeys for users whose API Credentials have the Validator role.

API	Description
POST v2/api/validation	Validates a single signed Pseudonymous Key or a signed batch of Pseudonymous Keys to ensure that they were generated by IDA. The mechanism used for signing is periodically changed. If validation returns HTTP Status 410 (Gone), the caller must request that the Operator requests a new Pseudonymous Key.

ApiCredential

The ApiCredential end-points are for the management of API Credentials by Interactive Users.

API	Description
GET v2/api/users/{id}/api-credentials	Returns the list of API credentials associated with the specified user. Only the Administrator who created the specified user or the user themselves can call this method, otherwise 403:Forbidden is returned.
DELETE v2/api/users/{id}/api-credentials	Delete all API Credentials from a specified Interactive User's list. Only the Administrator who created the specified user or the user themselves can call this method, otherwise 403:Forbidden is returned. If the target user is disabled a 400:BadRequest is returned. If the specified user is not known a 404:NotFound is returned.
DELETE v2/api/api-credentials/{id}	Deletes the specified API Credential. Only either the Interactive User who owns the specified API Credential or their associated Administrator can call this method, otherwise 403:Forbidden is returned. If the Interactive User is disabled a 400:BadRequest is returned. If the specified API Credential is not known a 404:NotFound is returned.
POST v2/api/api-credentials/{id}/enabled	(Re)enable/disable the specified API credential. Only either the Interactive User who owns the specified API Credential or their associated Administrator can call this method, otherwise 403:Forbidden is returned.
POST v2/api/users/{id}/api-credentials	Creates a new API credential for the specified user.

Operator

The Operator end-point allows a B2BGenerator to add a new API Credential for an operator with a newly generated Pseudonymous Key.

API	Description
POST v2/api/users/{id}/operator	Creates a new API Credential for an operator with a newly signed Pseudonymous Key. This API call can only be made by a user with the role B2BGenerator.

User

The User end-points are for administration of Interactive Users.

API	Description
GET v2/api/users	Returns a list of Interactive Users which the caller has created. This API call can only be made by a user with the role Administrator.
GET v2/api/users/{id}	Returns a specified user with a list of their API Credentials. This API call can be made by either the Administrator who created the target user or the target user themselves, otherwise a 403:Forbidden is returned.
POST v2/api/users	Creates a new Interactive User. This API call can only be made by a user with the role Administrator.
DELETE v2/api/users/{id}	Deletes the specified Interactive User, including any associated API Credentials. This API call can only be made by the Administrator who created the target user, otherwise a 403:Forbidden is returned. If the user is not known a 404:BadRequest is returned.
POST v2/api/users/{id}/name	Updates the name of the specified Interactive User to another valid name. This API call can be made by either the Administrator who created the target user or the target user themselves, otherwise a 403:Forbidden is returned.
POST v2/api/users/{id}/username	Updates the username of the specified Interactive User. This API call can be made by either the Administrator who created the target user or the target user themselves.
POST v2/api/users/{id}/password	Updates the password of the specified Interactive User to another valid password. This API call can be made by either the Administrator who created the target user or the target user themselves.
POST v2/api/users/{id}/enabled	Sets the activity of the specified Interactive User. Disabling a user also deactivates all associated API Credentials. Re-enabling a user sets them back to their exact previous active state - i.e. password and API Credentials are exactly as they were. This API call can only be made by the Administrator who created the target user.

Metrics

The Metric end-point provides the means to measure the activity of the of all end-points, for each user for the last twelve weeks.

API	Description
GET v2/api/api-counts	Returns the last 12 week's counts (by user) of the number of calls made to each endpoint. This API call can only be made by a user with the role Administrator.