Accessing the Identity
There are two mechanisms that allow a 3rd party to read protected information from an identity. The first is an HTTP Signature [[!HTTP-SIGNATURES]] based mechanism that allows any authorized client to access data that has been pre-approved by the entity that controls access to the identity information. The second is to use a browser-based mechanism that POSTs a request to an identity, allowing the identity owner to interactively decide what data access to allow or disallow.
The table below summarizes the HTTP Signatures-based [[!HTTP-SIGNATURES]] mechanism of accessing and modifying an identity:
| HTTP Method | Description of Action |
|---|---|
| GET |
Read all of the information that is available to the |
| POST | Used to perform operations on the identity for applications that are not capable of using HTTP Signatures [[!HTTP-SIGNATURES]] or to perform specific queries on the identity data. |
| PATCH | Modify information in the identity using the JSON Patch [[!JSON-PATCH]] protocol. |
| PUT | Replace the entire identity with the provided identity document. This operation SHOULD only be accessible to the owner of the identity. |
| DELETE | Deletes the identity. This operation SHOULD only be accessible to the owner of the identity. |
It's arguable that having a PUT or DELETE mechanism is useful. Both can be highly destructive and providing a common way to delete identities may be a bad thing if one experiences a security breach. In many cases, the identity document wouldn't be deleted, just merely marked as deleted in order to undelete it in the event of a mistake.
Not every Web application is capable of pre-arranging access to an identity, performing HTTP Signatures [[!HTTP-SIGNATURES]], or executing HTTP PATCH requests. In these cases, a regular HTTP POST mechanism is provided for Web applications to read, write, and query information about the identity.
| POST Parameter | Description of Action |
|---|---|
| action=query | Performs a query on the identity given a JSON-LD Frame in the POST body. |
| action=patch | Modify information in the identity using the JSON Patch [[!JSON-PATCH]] protocol. |
Reading Identity Information
Reading identity information can be performed in 3 different ways depending on
the sensitivity of the information being accessed. An
An identity can be accessed using a regular HTTP GET on the identity URL:
GET /identities/alice HTTP/1.1
Host: example.org
Date: Tue, 07 Jun 2013 20:51:35 GMT
If the Content-Type HTTP Header is not specified, a response using
the application/ld+json content type must be provided. Other
content types MAY be negotiated for between the client and server. The
application/ld+json content type is the only content type that
MUST be supported for all requests in this specification.
The result of the GET request SHOULD be information deemed to be public by the
{
"@context": "https://w3id.org/identity/v1",
"id": "https://example.org/identities/alice",
"type": ["Identity", "Person"],
"name": "Alice Smith"
"publicKey": [{ "id": "https://example.org/identities/alice/keys/1" }]
}
As the response above shows, the only information that the
name and a reference to their publicKey.
In order to access identity information that is not public, the request SHOULD be authenticated and authorized against a known identity. The HTTP Signatures [[!HTTP-SIGNATURES]] specification is used to digitally sign the request:
GET /identities/alice HTTP/1.1
Host: example.org
Date: Tue, 07 Jun 2013 20:52:12 GMT
Content-Type: application/ld+json
Authorization: Signature
keyId="http://example.org/identities/bob/keys/4",
algorithm="rsa-sha256",
headers="(request-line) host date content-type",
signature="Gm7W/r+e90REDpWyt.../VebAsNUtvQMe6cTjnDY="
The result of the GET request will now include information that the
{
"@context": "https://w3id.org/identity/v1",
"id": "https://example.org/identities/alice",
"type": ["Identity", "Person"],
"name": "Alice Smith",
"email": "asmith@example.com",
"mobileNumber": "4424672637162",
"publicKey": [{ "id": "https://example.org/identities/alice/keys/1" }]
}
As the response above shows, in addition to the public information, the
email and mobileNumber as well.
In the event that the 
Once the
POST /query?credentials=true&callback=https://flights.example.org/verify?session=7f8nddn HTTP/1.1
Host: login-hub.com
Date: Tue, 07 Jun 2013 20:52:12 GMT
Content-Type: application/ld+json
{
"@context": "https://w3id.org/identity/v1",
"id": "",
"name": "",
"governmentId": "",
"birthdate": ""
}
The result of the POST request will be a dialog that the
POST /verify?session=7f8nddn HTTP/1.1
Host: flights.example.org
Date: Tue, 07 Jun 2013 20:53:28 GMT
Content-Type: application/ld+json
{
"@context": "https://w3id.org/identity/v1",
"id": "https://example.org/identities/alice",
"type": ["Identity", "Person"],
"name": "Alice Smith",
"birthdate": "1988-11-02",
"governmentId": "321-54-9876"
"credential": [{
"id": "http://ssa.us.gov/credential/8273",
"type": "PassportCredential",
"claim": {
"id": "https://example.org/identities/alice",
"name": "Alice Smith",
"birthdate": "1988-11-02",
"governmentId": "321-54-9876"
},
"expires": "2017-02-04",
"signature": {
"type": "GraphSignature2012",
"creator": "https://ssa.us.gov/keys/27",
"signature": "fhhfiq3q9f8ahfh3q029rhaishsidfhf3780ey"
}
}]
}
As the response above shows, the credentials=true flag, the credentials for the information
requested have been included so that the
Credentials and Claims
It is possible for a 3rd party to provide digitally signed credentials to be stored with an identity. For example, if an individual would like to store digitally signed credentials verifiying their citizenship information, they would go through the following process:
- Go to a government website and start the verification process.
- Provide their identity URL to the government website.
- The government website would digitally sign a credential and attempt to write it to the provided identity.
- The individual would be provided with a dialog to authorize the write of the credential to their identity.
- If the authorization is successful, the digitally signed credential is written to the identity and will be returned in future queries for such a credential.
Writing Data to the Identity
There are two mechanisms that allow a 3rd party to write information
to an
The example below demonstrates a digitally signed request to write information
to a specific
POST /identities/alice?action=patch HTTP/1.1
Host: example.org
Date: Tue, 07 Jun 2013 20:52:12 GMT
Content-Type: application/json-patch+json
Authorization: Signature
keyId="https://ssa.us.gov/keys/27",
algorithm="rsa-sha256",
headers="(request-line) host date content-type",
signature="Gm7W/r+e90REDpWyt.../VebAsNUtvQMe6cTjnDY="
{
"op": "add",
"path": "https://w3id.org/identity#credential",
"value": {
"@context": "https://w3id.org/identity/v1",
"id": "http://ssa.us.gov/credential/8273",
"type": "PassportCredential",
"claim": {
"id": "https://example.org/identities/alice",
"name": "Alice Smith",
"birthdate": "1988-11-02",
"governmentId": "321-54-9876"
},
"expires": "2017-02-04",
"signature": {
"type": "GraphSignature2012",
"creator": "https://ssa.us.gov/keys/27",
"signature": "r+e90REDpW....bAsNUtvQM"
}
}
}
The example below demonstrates an unsigned request to write information
to a specific 
The data that is sent back and forth is outlined below:
POST /create?action=patch HTTP/1.1
Host: login-hub.com
Date: Tue, 07 Jun 2013 20:52:12 GMT
Content-Type: application/json-patch+json
{
"op": "add",
"path": "https://w3id.org/identity#credential",
"value": {
"@context": "https://w3id.org/identity/v1",
"id": "http://ssa.us.gov/credential/8273",
"type": "PassportCredential",
"claim": {
"id": "https://example.org/identities/alice",
"name": "Alice Smith",
"birthdate": "1988-11-02",
"governmentId": "321-54-9876"
},
"expires": "2017-02-04",
"signature": {
"type": "GraphSignature2012",
"creator": "https://ssa.us.gov/keys/27",
"signature": "r+e90REDpW....bAsNUtvQM"
}
}
}
The format for the message above is JSON-PATCH where the path
value is the complete URL for JSON-LD property to add to the