Back to top

Token Identity Service

This service stores user identities and information associated with those users. Users can be looked up by uuid or username.

In the long run, we would like to migrate this service to a decentalized identity service on the blockchain (using something like Blockstack, uPort, or others). We are still researching the best options.

Users

User Registration

Used to register a new username and associate it with a token id. The token id address is extracted from the signature.

Register a user
POST/v1/user

Example URI

POST https://identity.service.tokenbrowser.com/v1/user
Request
HideShow

The custom payload is optional, and can be used to hold extra information about a user. The username field is optional; if no username is provided one will be generated for the user.

Headers
Content-Type: application/json
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Body
{
  "about": "I'm a digital Dingus",
  "name": "Dingus McDingusface",
  "username": "testuser",
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "token_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "username": "testuser",
    "is_app": false,
    "name": "Dingus McDingusface",
    "about": "I'm a digital Dingus",
"avatar": null,
"location": null,
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "already_registered",
      "message": "The provided token id address is already registered"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "invalid_signature",
      "message": "Invalid Signature"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "invalid_timestamp",
      "message": "The difference between the timestamp and the current time is too large"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "missing_arguments",
      "message": "Missing arguments"
    }
  ]
}

Register a user without providing a username
POST/v1/user

Example URI

POST https://identity.service.tokenbrowser.com/v1/user
Request
HideShow
Headers
Content-Type: application/json
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "token_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": null,
    "username": "testuser",
    "is_app": false,
    "name": null,
"about": null,
"avatar": null,
"location": null,
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "username_taken",
      "message": "Requested username is already taken"
    }
  ]
}

Register an app/bot based user
POST/v1/user

Used when the registered id represents an app/bot, used by the services to know special handling of these users may be required.

Example URI

POST https://identity.service.tokenbrowser.com/v1/user
Request
HideShow
Headers
Content-Type: application/json
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Body
{
  "is_app": true,
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "token_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "username": "testuser",
    "name": null,
    "is_app": true,
"about": null,
"avatar": null,
"location": null,
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "username_taken",
      "message": "Requested username is already taken"
    }
  ]
}

Update a user
PUT/v1/user

Example URI

PUT https://identity.service.tokenbrowser.com/v1/user
Request
HideShow
Headers
Content-Type: application/json
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Body
{
  "username": "username",
  "name": "Test User"
}
Request
HideShow

Used to update a user’s avatar

Headers
Content-Type: multipart/form-data
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Content-Type: multipart/form-data; boundary=------------boundary
Body
<image encoded as mutilpart/form-data>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "token_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
  "username": "testuser",
  "is_app": false,
  "about": "I'm a digital Dingus",
  "name": "Dingus McDingusface",
  "avatar": "<url for new avatar>",
  "location": null
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "invalid_signature",
      "message": "Invalid Signature"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "missing_arguments",
      "message": "Missing arguments"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "username_taken",
      "message": "Requested username is already taken"
    }
  ]
}

User Retrieval/Update

Get a User's info
GET/v1/user/{id}

Example URI

GET https://identity.service.tokenbrowser.com/v1/user/1
URI Parameters
HideShow
id
string (required) Example: 1

username or ethereum address of the user

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "token_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "username": "testuser",
    "is_app": false,
"name": "Mr Tester"
"about": null,
"avatar": null,
"location": null
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
    "errors": [
        {
            "id": "not_found",
            "message": "Not found"
        }
}

Update a user
PUT/v1/user/{id}

Allows the user to update their profile

Example URI

PUT https://identity.service.tokenbrowser.com/v1/user/1
URI Parameters
HideShow
id
string (required) Example: 1

username or ethereum address of the user

Request
HideShow
Headers
Content-Type: application/json
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Body
{
  "name": "Mr Tester",
  "avatar": "https://s3.amazonaws.com/testuser/profile.jpg"
}
Request
HideShow

Used to update a user’s avatar

Headers
Content-Type: multipart/form-data
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Content-Type: multipart/form-data; boundary=------------boundary
Body
<image encoded as mutilpart/form-data>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "token_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
  "username": "testuser",
  "is_app": false,
  "avatar": "<url for new avatar>",
  "about": null,
  "name": "Mr Tester",
  "location": null
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
    "errors": [
        {
            "id": "not_found",
            "message": "Not found"
        }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errors": [
        {
            "id": "invalid_signature",
            "message": "Invalid Signature"
        }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "missing_arguments",
      "message": "Missing arguments"
    }
  ]
}

Utils

Timestamp generation

Used to retrieve a current timestamp from the server for use in signing other requests.

Get Timestamp
GET/v1/timestamp

Example URI

GET https://identity.service.tokenbrowser.com/v1/timestamp
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "timestamp": 1481291348
}

Id Service Login

Login

If sent signed, this will create an auth token for the user signing the request, and send that auth_token to all listeners of the request_token

If sent unsigned, this will wait for a signed request to generate an auth_token.

request_tokens will only live for 60 seconds. If the login takes longer, a new request_token must be created.

auth_tokens are single use, and only valid for 10 minutes.

Login
GET/v1/login/

Example URI

GET https://identity.service.tokenbrowser.com/v1/login/
Request
HideShow
Headers
Token-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Token-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Token-Timestamp: 1480077346
Response  204
HideShow
Headers
Content-Type: application/json
Request
HideShow
Headers
Accept: application/json
Body
{
  "auth_token": "dasuiHUDIYWGQIDsadwqDS"
}

Login

After being issues an auth_token the client would sent that token to the service it’s logging into, that service then uses this endpoint to verify the auth_token and to get the actual user details associated with that…

  • Request

    • Headers

      Accept: application/json
    • Body

      { “token_id”: “0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a”, “payment_address”: “0x056db290f8ba3250ca64a45d16284d04bc6f5fbf”, “username”: “testuser”, “is_app”: false, “about”: null, “avatar”: null, “name”: null, “location”: null }

Used by

Avatars

Get Identicon

Returns an identicon based off the given id address

Get Identicon
GET/identicon/.png

Example URI

GET https://identity.service.tokenbrowser.com/identicon/.png
Response  200
HideShow
Headers
Content-Type: image/png

Get Avatar

Returns the avatar set by PUT /user

Get Avatar
GET/avatar/.png

Example URI

GET https://identity.service.tokenbrowser.com/avatar/.png
Request  200
Response  200
HideShow
Headers
Content-Type: image/png
Etag: "<md5 hash of the image>"
Last-Modified: <date the avatar was last modified>
Body
<binary data>
Request  200
HideShow
Headers
If-None-Match: <Etag of cached image>
If-Modified-Since: <Last-Modified of cached image>
Response  200
HideShow

Returned if there there is a newer version of the image

Headers
Content-Type: image/png
Etag: "<md5 hash of the image>"
Last-Modified: "<date the avatar was last modified>"
Body
<binary data>
Response  304
HideShow

Returned if the cached image matches the existing image

Headers
Content-Type: image/png
Etag: "<md5 hash of the image>"
Last-Modified: "<date the avatar was last modified>"

Usage Notes

Errors

All error messages will return both machine (id) and human readable (message) error message. All errors, except validation_error, return only one error. Some errors will also have an optional link to the documentation (url).

validation_error with status code 400 is returned when the validation of the resource fails on POST or PUT requests. Response contains errors field with a list of errors.

Important: Different error types (id) can be added and removed over time so you should make sure your application accepts new ones as well.

  • Example 404 (application/json)

    { “errors”: [ { “id”: “not_found”, “message”: “Not found” } ] }

User Object

A User object has the following attributes:

  • username - with format ^[a-zA-Z][a-zA-Z0-9_]{2,59}$

  • token_id - ethereum address associated with the private key the user is using for identification

  • profile - user specified profile data

Generated by aglio on 19 Apr 2017