`/v1/identity` HTTP API
The HTTP endpoints in /v1/identity allow clients to generate and manage Spacetime public identities and private tokens.
At a glance
| Route | Description |
|---|---|
POST /v1/identity |
Generate a new identity and token. |
POST /v1/identity/websocket-token |
Generate a short-lived access token for use in untrusted contexts. |
GET /v1/identity/public-key |
Get the public key used for verifying tokens. |
GET /v1/identity/:identity/databases |
List databases owned by an identity. |
GET /v1/identity/:identity/verify |
Verify an identity and token. |
`POST /v1/identity`
Create a new identity.
Accessible through the CLI as spacetime identity new.
Returns
Returns JSON in the form:
{
"identity": string,
"token": string
} `POST /v1/identity/websocket-token`
Generate a short-lived access token which can be used in untrusted contexts, e.g. embedded in URLs.
Required Headers
| Name | Value |
|---|---|
Authorization |
A Spacetime token encoded as Basic authorization. |
Returns
Returns JSON in the form:
{
"token": string
} The token value is a short-lived JSON Web Token.
`GET /v1/identity/public-key`
Fetches the public key used by the database to verify tokens.
Returns
Returns a response of content-type application/pem-certificate-chain.
`POST /v1/identity/:identity/set-email`
Associate an email with a Spacetime identity.
Accessible through the CLI as spacetime identity set-email <identity> <email>.
Parameters
| Name | Value |
|---|---|
:identity |
The identity to associate with the email. |
Query Parameters
| Name | Value |
|---|---|
email |
An email address. |
Required Headers
| Name | Value |
|---|---|
Authorization |
A Spacetime token encoded as Basic authorization. |
`GET /v1/identity/:identity/databases`
List all databases owned by an identity.
Parameters
| Name | Value |
|---|---|
:identity |
A Spacetime identity. |
Returns
Returns JSON in the form:
{
"addresses": array<string>
} The addresses value is an array of zero or more strings, each of which is the address of a database owned by the identity passed as a parameter.
`GET /v1/identity/:identity/verify`
Verify the validity of an identity/token pair.
Parameters
| Name | Value |
|---|---|
:identity |
The identity to verify. |
Required Headers
| Name | Value |
|---|---|
Authorization |
A Spacetime token encoded as Basic authorization. |
Returns
Returns no data.
If the token is valid and matches the identity, returns 204 No Content.
If the token is valid but does not match the identity, returns 400 Bad Request.
If the token is invalid, or no Authorization header is included in the request, returns 401 Unauthorized.