Back to top

Toshi 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 toshi id. The toshi 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
Headers
Content-Type: application/json
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-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
{
  "toshi_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
  "username": "testuser",
  "is_app": false,
  "name": "Dingus McDingusface",
  "about": "I'm a digital Dingus",
  "avatar": null,
  "location": null,
  "public": true,
  "reputation_score": null,
  "review_count": 0,
  "average_rating": 0
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "id": "already_registered",
      "message": "The provided toshi 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
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-Timestamp: 1480077346
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "toshi_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
  "payment_address": null,
  "username": "testuser",
  "is_app": false,
  "name": null,
  "about": null,
  "avatar": null,
  "location": null,
  "public": true,
  "reputation_score": null,
  "review_count": 0,
  "average_rating": 0
}
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
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-Timestamp: 1480077346
Body
{
  "is_app": true,
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "toshi_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "username": "testuser",
    "name": null,
    "is_app": true,
    "about": null,
    "avatar": null,
    "location": null
    "public": true,
    "reputation_score": null,
    "review_count": 0,
    "average_rating": 0
}
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

Used to update a user’s profile.

  • Available Body Properties: payment_address, username, about, name, avatar, location

  • App only properties

    • categories: A list of category id’s or tags
  • Special Body Properties:

    • public: makes a user’s profile publicly visible in the browse page
    • is_app: marks the user as an app

Example URI

PUT https://identity.service.tokenbrowser.com/v1/user
Request
HideShow
Headers
Content-Type: application/json
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-Timestamp: 1480077346
Body
{
  "username": "username",
  "name": "Test User"
}
Request
HideShow
Headers
Content-Type: application/json
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-Timestamp: 1480077346
Body
{
  "username": "toshibot",
  "name": "ToshiBot",
  "is_app": true,
  "categories": [
    "social",
    "cats"
  ]
}
Request
HideShow

Used to update a user’s avatar

Headers
Content-Type: multipart/form-data
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-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
{
  "toshi_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,
  "public": true,
  "reputation_score": 2.3,
  "review_count": 10,
  "average_rating": 4.5
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "toshi_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "username": "toshibot",
    "is_app": true,
    "name": "ToshiBot",
    "location": null,
    "public": false,
    "categories": [{"id": 1, "tag": "social", "name": "Social", {"id": 2, "tag": "cats", "name": "Cats"}],
    "reputation_score": 2.3,
    "review_count": 10,
    "average_rating": 4.5
}
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
{
    "toshi_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
    "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "username": "testuser",
    "is_app": false,
    "name": "Mr Tester"
    "about": null,
    "avatar": null,
    "location": null,
    "public": true,
    "reputation_score": 2.3,
    "review_count": 10,
    "average_rating": 4.5
}
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
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-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
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-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
{
  "toshi_id": "0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a",
  "payment_address": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
  "username": "testuser",
  "is_app": false,
  "avatar": "<url for new avatar>",
  "about": null,
  "name": "Mr Tester",
  "location": null,
  "public": true,
  "reputation_score": 2.3,
  "review_count": 10,
  "average_rating": 4.5
}
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
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-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

      { “toshi_id”: “0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a”, “payment_address”: “0x056db290f8ba3250ca64a45d16284d04bc6f5fbf”, “username”: “testuser”, “is_app”: false, “about”: null, “avatar”: null, “name”: null, “location”: null, “public”: true, “reputation_score”: 2.3, “review_count”: 10, “average_rating”: 4.5 }

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>"

Reports

Report User/App

Used to send a report about the user/app

Send Report
POST/v1/report

Example URI

POST https://identity.service.tokenbrowser.com/v1/report
Request
HideShow
Headers
Content-Type: application/json
Toshi-ID-Address: 0x676f7cb80c9ff6a55e8992d94bac9a3212282c3a
Toshi-Signature: 0xc39a479a92fe8d626324ff82a33684610ecd6b50714f59542a1ea558220ec6246a9193dd481078417b3b44d55933989587459d3dd50295d4da67d6580ac8646801
Toshi-Timestamp: 1480077346
Body
{
    "toshi_id": "0x056db290f8ba3250ca64a45d16284d04bc6f5fbf",
    "details": "app is fraudulent",
}
Response  204

Categories

List available app categories

Send Report
GET/v1/categories

Example URI

GET https://identity.service.tokenbrowser.com/v1/categories
Request
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "categories": [
        {
            "id": 1,
            "tag": "help",
            "name": "Help"
        },
        {
            "id": 2,
            "tag": "cats",
            "name": "Cats"
        },
        {
            "id": 3,
            "tag": "games",
            "name": "Games"
        },
        {
            "id": 4,
            "tag": "social",
            "name": "Social"
        }
    }
}

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}$

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

  • profile - user specified profile data

Generated by aglio on 14 Aug 2017