Personas

This page contains all relevant APIs interacting with Disco Personas.

Introduction

User

A User on the Disco platform is the holder and owner of its own identity. A User can be an individual or an organization. User have an Ethereum Address that is used with their wallet for access to their credentials. Users may, or may not, have a www domain and/or Ethereum Name Service (ENS) linked to their identity.

Persona

A Persona is a set of attributes that describes a User in a particular context. Currently, Disco supports one Persona per User (extendable to N Personas per User in future releases). A Persona may have multiple DIDs, and account Linkages assigned.

An example of a Persona Document

{
    "id": "de0eae21-b88f-4f22-ad92-7ed99f7ea05c",
    // Unique user ID assigned by Disco
    "user": {
        "id": "ae541371-590b-4dba-b783-5cde41cc0d3c"
    },
    // The User's DID(s) - most users will have a did:3 or a did:pkr ID, whereas
    // organiozations may have a did:web ID
    "dids": [
        {
            "did": "did:web:api.disco.xyz/v1/disco"
        }
    ],
    // Disco user handle
    "handle": "Disco",
    // Link to user's avatar
    "avatarUri": "https://pbs.twimg.com/profile_images/1544599788464766976/Ib49kkdh_400x400.jpg",
    // User bio
    "bio": "Disco's ecosystem is build around our Verifiable Data Registry.",
    // The User's DID and accossiated Ethereum Address
    "ethAddress": "0x08936438bfb8e9b269f978d5327ad687f47g8c08",
    // External account links that the user has linked to one their Disco DIDs 
    "links": [
        {
            "accountType": "Discord",
            // Linked account handle
            "handle": "Disco#1234",
            // Verified by Disco
            "verified": true,
            // The user DID the linked to the account
            "did": "did:web:api.disco.xyz/v1/disco",
            "proof": "https://discord.com/channels/947857036257935390/975763597529600041/1078306074618236980"
        },
        {
            "accountType": "Twitter",
            "handle": "DiscoXYZ",
            "verified": true,
            "did": "did:web:api.disco.xyz/v1/disco",
            "proof": "https://twitter.com/DiscoXYZ/status/1667219955002032136"
        }
    ]
}

Use Cases

Get Persona for a DID

This response is less verbose as it only includes current snapshot of a DID's persona.

Persona Meatadata

Returns Persona metadata for a DID holder. Persona metadata is composed of avatar links, username, color schemes, and verified account handles (such as Twitter, Discord, etc.).

GET/v1/persona/did/metadata/{did}

Path parameters

did*string

The holder's DID to retrieve Persona metadata for

Example: "did:web:api.disco.xyz/v1/disco"

Response

200400

Returns a persona document for the DID owner

Body

*/*

object

Request

JavaScriptCurlPython

const response = await fetch('/v1/persona/did/metadata/{did}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

400

{
  "name": "BAD_REQUEST",
  "message": "text",
  "status": 400,
  "errors": [
    {
      "name": "text",
      "message": "text"
    }
  ],
  "stack": "text"
}

Usage example

Curl

curl --location 'https://api.disco.xyz/v1/persona/did/metadata/did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb' \
--header 'Authorization: Bearer <your Disco API key>'

JavaScript

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <your Disco API key>");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.disco.xyz/v1/persona/did/metadata/did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Successful Response

{
    "orgBrand": {
        "textColor": null,
        "brandColor": null,
        "backgroundImage": null
    },
    "avatar": "https://uploads-ssl.webflow.com/634f227dc666d2739c1c3959/634f227dc666d26bd21c3a55_14-%20Evin%20McMullen%20original%20BW.png",
    "accountLinks": [
        {
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "type": "Discord",
            "handle": "heyevin"
        },
        {
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "type": "Twitter",
            "handle": "provenauthority"
        }
    ],
    "username": "provenauthority"
}

Get Persona for a DID

This response may be very verbose as it includes all accounts (re)link attempts and their proofs.

Persona Metadata

Returns Persona metadata for a DID holder. Persona metadata is composed of avatar links, username, color schemes, and verified account handles (such as Twitter, Discord, etc.).

GET/v1/persona/did/{did}

Path parameters

did*string

Response

200400

Returns a persona document for the DID owner

Body

*/*

object

Request

JavaScriptCurlPython

const response = await fetch('/v1/persona/did/{did}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

400

{
  "name": "BAD_REQUEST",
  "message": "text",
  "status": 400,
  "errors": [
    {
      "name": "text",
      "message": "text"
    }
  ],
  "stack": "text"
}

Usage example

Curl

curl --location 'https://api.disco.xyz/v1/credential/verify' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Authorization: Bearer <your Disco API key>' \
curl --location 'https://api.disco.xyz/v1/persona/did/did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb' \
--header 'Authorization: Bearer <your Disco API key>'

JavaScript

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <your Disco API key>");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.disco.xyz/v1/persona/did/did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Successful Response

{
    "id": "3045c158-af4a-417f-a67f-bc8f916b5408",
    "user": {
        "id": "12a9e548-a2fb-42c6-ba4b-e931127baa4a"
    },
    "dids": [
        {
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "ethAddr": "0x9c7b16e49c2f579453c45ca0bf7771a43dc61449"
        }
    ],
    "handle": "provenauthority",
    "avatarUri": "https://uploads-ssl.webflow.com/634f227dc666d2739c1c3959/634f227dc666d26bd21c3a55_14-%20Evin%20McMullen%20original%20BW.png",
    "bio": "GM and welcome to the Disco! ",
    "ethAddress": "0x9c7b16e49c2f579453c45ca0bf7771a43dc61449",
    "links": [ // This object holds all the account links for the ID
        {
            "accountType": "Discord",
            "handle": "heyevin",
            "verified": true,
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "proof": "https://discord.com/channels/947857036257935390/975763597529600041/1128736725682892930"
        },
        {
            "accountType": "Twitter",
            "handle": "provenauthority",
            "verified": true,
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "proof": "https://twitter.com/provenauthority/status/1674454543420260352"
        }
    ],
    "metadata": {
        "orgBrand": {
            "textColor": null,
            "brandColor": null,
            "backgroundImage": null
        },
        "avatar": "https://uploads-ssl.webflow.com/634f227dc666d2739c1c3959/634f227dc666d26bd21c3a55_14-%20Evin%20McMullen%20original%20BW.png",
        "accountLinks": [ // This object holds all link activity for linked accounts. A user can unlink/relink their accounts and this section will show an item for each linking attempt.
            {
                "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
                "type": "Discord",
                "handle": "heyevin"
            },
            {
                "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
                "type": "Discord",
                "handle": "heyevin"
            },
            {
                "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
                "type": "Twitter",
                "handle": "provenauthority"
            }
        ],
        "username": "provenauthority"
    },
    "isOrg": true // If true it indicates that this identity is classified as an orginization.
}

Get Persona for an Ethereum address

This response may be very verbose as it includes all accounts (re)link attempts and their proofs.

Get persona by Ethereum Address

Returns a profile via its linked Ethereum Address. Usually in the format: 0xABC1234567890

GET/v1/persona/find/eth/{eoa}

Path parameters

eoa*string

Ethereum Address

Example: "0xABC1234567890"

Response

200400404

Returns a persona document for the DID owner

Body

*/*

object

Request

JavaScriptCurlPython

const response = await fetch('/v1/persona/find/eth/{eoa}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

400404

{
  "name": "BAD_REQUEST",
  "message": "text",
  "status": 400,
  "errors": [
    {
      "name": "text",
      "message": "text"
    }
  ],
  "stack": "text"
}

Usage example

Curl

curl --location 'https://api.disco.xyz/v1/persona/find/eth/0x9c7b16e49c2f579453c45ca0bf7771a43dc61449' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <your Disco API key>'

JavaScript

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer <your Disco API key>");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.disco.xyz/v1/persona/find/eth/0x9c7b16e49c2f579453c45ca0bf7771a43dc61449", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Successful Response

{
    "id": "3045c158-af4a-417f-a67f-bc8f916b5408",
    "user": {
        "id": "12a9e548-a2fb-42c6-ba4b-e931127baa4a"
    },
    "dids": [
        {
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "ethAddr": "0x9c7b16e49c2f579453c45ca0bf7771a43dc61449"
        }
    ],
    "handle": "provenauthority",
    "avatarUri": "https://uploads-ssl.webflow.com/634f227dc666d2739c1c3959/634f227dc666d26bd21c3a55_14-%20Evin%20McMullen%20original%20BW.png",
    "bio": "GM and welcome to the Disco! ",
    "ethAddress": "0x9c7b16e49c2f579453c45ca0bf7771a43dc61449",
    "links": [
        {
            "accountType": "Discord",
            "handle": "heyevin",
            "verified": true,
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "proof": "https://discord.com/channels/947857036257935390/975763597529600041/1128736725682892930"
        },
        {
            "accountType": "Discord",
            "handle": "heyevin",
            "verified": true,
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "proof": "https://twitter.com/provenauthority/status/1674454543420260352"
        },
        {
            "accountType": "Twitter",
            "handle": "provenauthority",
            "verified": true,
            "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
            "proof": "https://twitter.com/provenauthority/status/1674454543420260352"
        }
    ],
    "metadata": {
        "orgBrand": {
            "textColor": null,
            "brandColor": null,
            "backgroundImage": null
        },
        "avatar": "https://uploads-ssl.webflow.com/634f227dc666d2739c1c3959/634f227dc666d26bd21c3a55_14-%20Evin%20McMullen%20original%20BW.png",
        "accountLinks": [
            {
                "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
                "type": "Discord",
                "handle": "heyevin"
            },
            {
                "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
                "type": "Discord",
                "handle": "heyevin"
            },
            {
                "did": "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb",
                "type": "Twitter",
                "handle": "provenauthority"
            }
        ],
        "username": "provenauthority"
    },
    "isOrg": true
}

Search for Profile by account linkages

Returns DIDs of matching handles given search input. Can search for Twitter, Discord, or Domain handle in one endpoint.

Search by any handle

GET https://api.disco.xyz/v1/search/?handle=provenauthority

Query Parameters

Name	Type	Description
handle	String	handle of Account Linked to search for. This can be a twitter, discord, or domain.

200: OK Successful Operation

Example Response

[
    "did:3:kjzl6cwe1jw14b7xqq94oiy0lcnndgyt0p3vtlnsscpljosx6gom46qkxcv8sjb"
]

401: Unauthorized Unauthorized. Request not authenticated, API token is missing or invalid!

403: Forbidden Forbidden. You don't have access to the relevant resource.

404: Not Found Resource not found