⚡️ Quickstart Guide

Takes 5 minutes!

Prerequisites

You will need an API Key and any library or app capable of making http requests (Postman, Fetch, Axios, Httpie, etc)

Get started with Disco in only three steps:

Get an API key
Select a credential schema
Build and issue credential(s)

Introduction

The Disco API enables developers to issue Verifiable Credentials to addresses and to fetch and validate credentials about those addresses. These credentials use standard data models (schemas), contain event metadata or attestations, and can be later fetched and relied upon to bootstrap onboarding, manage access control, and understand community insights.

Prerequisites

You will need to create an API key, steps to create one:

Create a test account in our dashboard https://dashboard.disco.xyz/login
Go to the Admin section and click on API Keys
Create an API Key

Video and more details are found in Generate an API Key section.

Select a Credential Schema

Schemas define the structure and contents of a credential – enabling them to be consistent, verifiable, and interoperable. More details in Schemas 101. View Disco's public Github repository of schemas.

The directions below use the Membership Credential schema.

Always use Schemas raw files, example.

How to use the API to Build and Issue or Fetch credentials

This method constructs a Membership Credential Schema, signed by Disco-controlled keys.

Issue Credentials

Generate and issue credentials to an ETH address or Decentralized Identifier (DID).

Programmatically issue one verifiable credential

Generate and return a signed Credential. This will also write the Credential the recipient's data backpack in Disco's Verifiable Data Registry. The JSON body should contain required Credential values for the schema type used. Available schemas and their specifications can be found at https://github.com/discoxyz/disco-schemas.

POST/v1/credential

Body

The JSON body should contain specific credential schema values required for the Credential type used. Available schemas can be found at https://github.com/discoxyz/disco-schemas.

schemaUrlschemaUrl

The URL of the verifiable crednetial schema. Available schemas can be found at https://github.com/discoxyz/disco-schemas

Example: "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json"

recipientDIDrecipientDID

The DID address of the credential's claimant

Example: "did:3:Example987xyz"

subjectDatasubjectData

The fields and values for the credential (based on its schema)

Example:

"{\n    \"memberId\": \"Goldstar Member\",\n    \"membershipDescription\": \"Demo membership to showcase Disco API\",\n    \"membershipLevel\": \"Permanent\",\n    \"membershipType\": \"Developer\",\n    \"organization\": \"Disco.xyz\"\n  }"

expirationDateexpirationDate

The date for the credential to expire for the claimant. Leave empty if there's no expiration.

Example: ""

suitesuite

Optional - supported values are "JWT" and "712".

Example: ""

issuerissuer

The DID address of the credential's issuer.

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

skipSignskipSign

To sign or not to sign - hint you should sign! Either leave out or assign false.

Example: "false"

Response

Success

Body

_idDatabase ID

Internal ID used by data storage system

vcvc

Verifiable Credential payload

Example: "See https://www.w3.org/TR/vc-data-model/#example-a-simple-example-of-a-verifiable-credential"

jwtJWT

JSON Web Token per RFC 7519

Example: "eyJhbGciOiJIUzI1N........"

isPublicPublic/Private Flag

If true anyone can read the credential. If false, only the issuer and the claimant can read the credential.

Example: "true"

issuerVerifiable Credential Issuer

JSON Web Token per RFC 7519

Example: ""

recipientHolder or claimant of Verifiable Credential

The DID value for the recipient of Verifiable Credential.

subjectSubject of Credential

Subject is what the credential claim is made about.

schemaschema

The URL of the verifiable crednetial schema. Available schemas can be found at https://github.com/discoxyz/disco-schemas

Example: "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json"

genIdUnique Verifiable Credential ID

updatedAtLatest update date and time

isDeletedSoft-delete flag

historyList of changes to the credential, if any.

Request

const response = await fetch('/v1/credential', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "_id": "text",
  "vc": "See https://www.w3.org/TR/vc-data-model/#example-a-simple-example-of-a-verifiable-credential",
  "jwt": "eyJhbGciOiJIUzI1N........",
  "isPublic": "true",
  "issuer": "",
  "recipient": "text",
  "subject": "text",
  "schema": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
  "genId": "text",
  "updatedAt": "text",
  "isDeleted": false,
  "history": []
}

Usage example

curl --location 'https://api.disco.xyz/v1/credential' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Authorization: Bearer <your Disco API key>' \
--data '{
    "issuer": "did:3:123abcexample",
    "schemaUrl": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
    "recipientDID": "did:3:456defexample",
    "subjectData": {
        "memberId": "123XYZ",
        "membershipDescription": "Demo membership to showcase Disco API",
        "membershipLevel": "Permanent",
        "membershipType": "Developer",
        "organization": "Disco.xyz"
    },
    "expirationDate": ""
}'

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

var raw = JSON.stringify({
  "issuer": "did:3:123abcexample",
  "schemaUrl": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
  "recipientDID": "did:3:456defexample",
  "subjectData": {
    "memberId": "123XYZ",
    "membershipDescription": "Demo membership to showcase Disco API",
    "membershipLevel": "Permanent",
    "membershipType": "Developer",
    "organization": "Disco.xyz"
  },
  "expirationDate": ""
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

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

Successful Response

Response

{
    "vc": {
        "@context": [
            "https://www.w3.org/2018/credentials/v1"
        ],
        "type": [
            "VerifiableCredential",
            "MembershipCredential"
        ],
        "issuer": {
            "id": "did:3:123abcexample"
        },
        "issuanceDate": "2023-10-10T12:53:15.718Z",
        "id": "https://api.disco.xyz/credential/5c7cca5e-56ab-4e08-87f6-817e9f89f507",
        "credentialSubject": {
            "id": "did:3:456defexample",
            "memberId": "123XYZ",
            "membershipDescription": "Demo membership to showcase Disco API",
            "membershipLevel": "Permanent",
            "membershipType": "Developer",
            "organization": "Disco.xyz"
        },
        "credentialSchema": {
            "id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
            "type": "JsonSchemaValidator2018"
        },
        "proof": {
            "verificationMethod": "did:3:kjzl6cwe1jw14a7u9sx3thx9gg9uh7u5tqjkzcnr5pi5zzkap7kiztgsfhzayzt#controller",
            "created": "2023-10-10T12:53:15.745Z",
            "proofPurpose": "assertionMethod",
            "type": "EthereumEip712Signature2021",
            "proofValue": "0x487aa8ad7c90aa34a108b52cd7e23c5ef6cf9cfbdc01d7741d70d6b8f79763dc65df429e558af4c2d7a54c7f4040cf874ecffa95f17d87d8dc07823b23324bfe1b",
            "eip712Domain": {
                "domain": {
                    "chainId": 1,
                    "name": "Disco Verifiable Credential",
                    "version": "1"
                },
                "messageSchema": {
                    "EIP712Domain": [
                        {
                            "name": "name",
                            "type": "string"
                        },
                        {
                            "name": "version",
                            "type": "string"
                        },
                        {
                            "name": "chainId",
                            "type": "uint256"
                        }
                    ],
                    "Proof": [
                        {
                            "name": "created",
                            "type": "string"
                        },
                        {
                            "name": "proofPurpose",
                            "type": "string"
                        },
                        {
                            "name": "type",
                            "type": "string"
                        },
                        {
                            "name": "verificationMethod",
                            "type": "string"
                        }
                    ],
                    "Issuer": [
                        {
                            "name": "id",
                            "type": "string"
                        }
                    ],
                    "CredentialSubject": [
                        {
                            "name": "id",
                            "type": "string"
                        },
                        {
                            "name": "organization",
                            "type": "string"
                        }
                    ],
                    "VerifiableCredential": [
                        {
                            "name": "@context",
                            "type": "string[]"
                        },
                        {
                            "name": "credentialSubject",
                            "type": "CredentialSubject"
                        },
                        {
                            "name": "id",
                            "type": "string"
                        },
                        {
                            "name": "issuanceDate",
                            "type": "string"
                        },
                        {
                            "name": "issuer",
                            "type": "Issuer"
                        },
                        {
                            "name": "proof",
                            "type": "Proof"
                        },
                        {
                            "name": "type",
                            "type": "string[]"
                        }
                    ]
                },
                "primaryType": "VerifiableCredential"
            }
        }
    },
    "isPublic": false,
    "issuer": "did:3:123abcexample",
    "recipient": "did:3:456defexample",
    "subject": "did:3:456defexample",
    "schema": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
    "isDeleted": false,
    "genId": "a4282add-ed1f-429d-a80d-abdd675b2eef",
    "updatedAt": "2023-10-10T12:53:15.748Z",
    "history": [],
    "_id": "6525493bb8ffec6244182e03"
}

Fetch Credentials

Fetch a public credential based on its ID

Returns a single credential using its `vc.id`

Returns a single credential using its verifiable credential ID (vc.id) - assuming the Api Key holder is either the holder, issuer or the Credential is public.

GET/v1/credential/{id}

Path parameters

id*string

Unique ID of Credential

Example: "\"did:3:123abcexample#someuuid\""

Response

A Verifiable Credential document

Body

_idDatabase ID

Internal ID used by data storage system

vcvc

Verifiable Credential payload

Example: "See https://www.w3.org/TR/vc-data-model/#example-a-simple-example-of-a-verifiable-credential"

jwtJWT

JSON Web Token per RFC 7519

Example: "eyJhbGciOiJIUzI1N........"

isPublicPublic/Private Flag

If true anyone can read the credential. If false, only the issuer and the claimant can read the credential.

Example: "true"

issuerVerifiable Credential Issuer

JSON Web Token per RFC 7519

Example: ""

recipientHolder or claimant of Verifiable Credential

The DID value for the recipient of Verifiable Credential.

subjectSubject of Credential

Subject is what the credential claim is made about.

schemaschema

The URL of the verifiable crednetial schema. Available schemas can be found at https://github.com/discoxyz/disco-schemas

Example: "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json"

genIdUnique Verifiable Credential ID

updatedAtLatest update date and time

isDeletedSoft-delete flag

historyList of changes to the credential, if any.

Request

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

Response

{
  "_id": "text",
  "vc": "See https://www.w3.org/TR/vc-data-model/#example-a-simple-example-of-a-verifiable-credential",
  "jwt": "eyJhbGciOiJIUzI1N........",
  "isPublic": "true",
  "issuer": "",
  "recipient": "text",
  "subject": "text",
  "schema": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
  "genId": "text",
  "updatedAt": "text",
  "isDeleted": false,
  "history": []
}

Usage example

# Looking up id=https://api.disco.xyz/credential/22d9187b-8a33-4e17-b05f-c8192107ab28
curl --location 'https://api.disco.xyz/v1/credential/https%3A%2F%2Fapi.disco.xyz%2Fcredential%2F22d9187b-8a33-4e17-b05f-c8192107ab28' \
--header 'Authorization: Bearer <your Disco API key>'

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/credential/https%3A%2F%2Fapi.disco.xyz%2Fcredential%2F3f929a36-8e1c-46c1-9981-120b43241c13", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Successful response

Response

{
    "_id": "65099e2e52bf698c21aeeb91",
    "vc": {
        "@context": [
            "https://www.w3.org/2018/credentials/v1"
        ],
        "type": [
            "VerifiableCredential",
            "MembershipCredential"
        ],
        "issuer": {
            "id": "did:3:kjzl6cwe1jw14a7u9sx3thx9gg9uh7u5tqjkzcnr5pi5zzkap7kiztgsfhzayzt"
        },
        "issuanceDate": "2023-09-19T13:12:14.801Z",
        "id": "https://api.disco.xyz/credential/22d9187b-8a33-4e17-b05f-c8192107ab28",
        "credentialSubject": {
            "id": "did:ethr:0x08936438bfb8e9b269f978d5327ad684f47f8c05",
            "organization": "House of Leroy"
        },
        "expirationDate": "2024-08-29T00:00:00.000Z",
        "credentialSchema": {
            "id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
            "type": "JsonSchemaValidator2018"
        },
        "proof": {
            "verificationMethod": "did:3:kjzl6cwe1jw14a7u9sx3thx9gg9uh7u5tqjkzcnr5pi5zzkap7kiztgsfhzayzt#controller",
            "created": "2023-09-19T13:12:14.827Z",
            "proofPurpose": "assertionMethod",
            "type": "EthereumEip712Signature2021",
            "proofValue": "0x3aa89255fe63d7ca70c43b0603aa3d004978bc0815b35ae5dcbf84a3df4867f133b6f0d717916cf84b8f6b3dcbf6a7643f18fa00557c0ddb5f5571cc8f678d291c",
            "eip712Domain": {
                "domain": {
                    "chainId": 1,
                    "name": "Disco Verifiable Credential",
                    "version": "1"
                },
                "messageSchema": {
                    "EIP712Domain": [
                        {
                            "name": "name",
                            "type": "string"
                        },
                        {
                            "name": "version",
                            "type": "string"
                        },
                        {
                            "name": "chainId",
                            "type": "uint256"
                        }
                    ],
                    "Proof": [
                        {
                            "name": "created",
                            "type": "string"
                        },
                        {
                            "name": "proofPurpose",
                            "type": "string"
                        },
                        {
                            "name": "type",
                            "type": "string"
                        },
                        {
                            "name": "verificationMethod",
                            "type": "string"
                        }
                    ],
                    "Issuer": [
                        {
                            "name": "id",
                            "type": "string"
                        }
                    ],
                    "CredentialSubject": [
                        {
                            "name": "id",
                            "type": "string"
                        },
                        {
                            "name": "organization",
                            "type": "string"
                        }
                    ],
                    "VerifiableCredential": [
                        {
                            "name": "@context",
                            "type": "string[]"
                        },
                        {
                            "name": "credentialSubject",
                            "type": "CredentialSubject"
                        },
                        {
                            "name": "id",
                            "type": "string"
                        },
                        {
                            "name": "issuanceDate",
                            "type": "string"
                        },
                        {
                            "name": "issuer",
                            "type": "Issuer"
                        },
                        {
                            "name": "proof",
                            "type": "Proof"
                        },
                        {
                            "name": "type",
                            "type": "string[]"
                        }
                    ]
                },
                "primaryType": "VerifiableCredential"
            }
        }
    },
    "isPublic": true,
    "issuer": "did:3:kjzl6cwe1jw14a7u9sx3thx9gg9uh7u5tqjkzcnr5pi5zzkap7kiztgsfhzayzt",
    "recipient": "did:ethr:0x08936438bfb8e9B269F978D5327Ad684f47F8C05",
    "subject": "did:ethr:0x08936438bfb8e9B269F978D5327Ad684f47F8C05",
    "schema": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
    "isDeleted": false,
    "genId": "9af80795-09f5-48a7-abd7-d713a8cd2447",
    "updatedAt": "2023-09-20T18:34:29.629Z",
    "history": [
        "{\"field\":\"isPublic\",\"oldValue\":false,\"newValue\":true,\"updatedAt\":\"2023-09-20T18:34:29.629Z\"}"
    ]
}

Community and Support

Join our Discord! You can also contact us at ask@disco.xyz.

PreviousLifecycle of Credentials NextCustomize Credential Branding

Last updated 7 months ago