Identity assertion
The identity assertion interface is exposed by the Identity Service and follows VIN-2 Identity Federation. Through it a member system obtains a signed statement that a person or a system has been authenticated, presents that statement to another system, and has it verified. The interface is the means by which one account, issued through a member organisation, gives access to every shared system of the Velocity Interoperability Network.
| Particular | Value |
|---|---|
| Catalogue identifier | API-02 |
| Provider | Identity Service |
| Standard followed | VIN-2 Identity Federation |
| Interface version | 0.9 |
| Status | Interim |
| Listed | 6 September 2026 |
The interface has two kinds of user. A relying system accepts assertions as proof of identity and never handles passwords itself. A calling system requests an assertion for its own identity so that it may use other interfaces: every request to the registry lookup, the incident submission and the notice feed carries an assertion obtained here.
Operations. The interface offers four operations.
| Operation | Purpose | Request | Response |
|---|---|---|---|
| Request assertion | Issues a signed assertion for a person who has signed in through the Identity Service, or for a member system acting on its own behalf. | Account reference and the identifier of the relying system | One assertion, valid for twelve hours |
| Verify assertion | Confirms that an assertion was issued by the Identity Service, has not expired and has not been revoked. | One assertion | Valid or invalid, with the subject, issuing organisation and assurance level if valid |
| Revoke assertion | Withdraws an assertion before it expires, for example when a person signs out or an account is closed. | One assertion identifier | Acknowledgement with the time of revocation |
| Retrieve signing keys | Returns the public keys with which assertions are signed, so that a relying system may verify signatures locally. | None | Current and next signing keys, each with the dates between which it is valid |
The assertion. An assertion carries the following fields. All are present in every assertion.
| Field | Meaning |
|---|---|
| Assertion identifier | Unique reference of the assertion, used to revoke it. |
| Subject | The account reference of the person, or the system identifier, whose identity is asserted. |
| Issuing organisation | The member key of the organisation that requested the account. |
| Relying system | The identifier of the system for which the assertion was issued. An assertion is valid only for that system. |
| Assurance level | 1, 2 or 3, stating how the subject was authenticated. |
| Issued at | Time of issue. |
| Expires at | Time of expiry, twelve hours after issue. |
| Signature | Signature of the Identity Service over all other fields, made with a key obtainable through Retrieve signing keys. |
Acting as a relying system. A member system that wishes to accept assertions follows the procedure below.
Step 1: Register the system with the Identity Service
A member organisation registers each relying system by writing to the Identity Service through its own procedures. The system identifier is issued on registration and appears in every assertion issued for it.
Step 2: Direct the person to sign in
A relying system does not collect passwords. It directs the person to the Identity Service, which authenticates them and returns an assertion for the relying system.
Step 3: Verify the assertion
The relying system verifies the signature against the current signing keys, or calls Verify assertion. It checks that the relying-system field names itself and that the assertion has not expired.
Step 4: Apply the assurance level
The relying system decides what the subject may do according to the assurance level. A system that requires level 2 must refuse an assertion at level 1 rather than accept it with reduced access.
Step 5: Revoke on sign-out
When the person signs out, the relying system calls Revoke assertion so that the assertion cannot be presented again.
Error conditions. A request that cannot be answered receives one of the following results.
- Unknown account
- The account reference supplied is not held by the Identity Service. No assertion is issued.
- Account closed
- The account exists but has been closed by the member organisation or after eighteen months without a sign-in. No assertion is issued.
- Relying system not registered
- The system identifier supplied has not been registered by a member organisation. No assertion is issued.
- Assertion expired or revoked
- Returned by Verify assertion. The assertion was valid when issued but may no longer be relied upon.
- Signature invalid
- Returned by Verify assertion. The assertion was not issued by the Identity Service, or has been altered. Treat the presenting system as unauthenticated.
Versions. The interface is Interim at Version 0.9. The set of operations and the fields of the assertion are not expected to change before confirmation. Changes are announced on this page and recorded in the API Catalogue.
6 September 2026
Version 0.9 listed as Interim
All four operations available. Assurance levels 1 to 3 defined. Twelve-hour validity fixed.
Forthcoming
Confirmation at Version 1.0
Expected after the first review of VIN-2 in March 2027.
Questions about the interface may be sent to contact@developer.gov.vin and are passed to the Identity Service where they concern its operation. Questions about the issue of accounts are for the member organisation concerned. The standard the interface follows is described under Standards.