API docs by Redocly

BitBadges API (0.1)

Download OpenAPI specification:Download

The BitBadges API is a RESTful API that allows developers to interact with the BitBadges blockchain and indexer. The API provides endpoints for retrieving account details, collections, badges, and more. The API requires an API key for authentication.

Accounts

Get Accounts

Retrieves accounts and accompanying details.

Authorizations:
(apiKeyuserMaybeSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
required
Array of objects (AccountFetchDetails)

Responses

Request samples

Content type
application/json
{
  • "accountsToFetch": [
    ]
}

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Update Profile

Updates the profile/account information for a user. Only the provided fields will be updated.

Authorizations:
(apiKeyuserSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
discord
string

The Discord username.
twitter
string

The Twitter username.
github
string

The GitHub username.
telegram
string

The Telegram username.
seenActivity
any (UNIXMilliTimestamp)

The last seen activity timestamp.
readme
string

The README details (markdown supported).
Array of objects (iBatchBadgeDetails)

The badges to hide and not view for this profile's portfolio
hiddenLists
Array of strings

The lists to hide and not view for this profile's portfolio
object

An array of custom pages on the user's portolio. Used to customize, sort, and group badges / lists into pages.

object

The watchlist of badges / lists
profilePicUrl
string

The profile picture URL.
username
string

The username.
profilePicImageFile
any

The profile picture image file to set. We will then upload to our CDN.
object

The notification preferences for the user. Will only be returned if user is authenticated with full access.
object

Approved sign in methods. Only returned if user is authenticated with full access.
object (iSocialConnections)

The social connections for the user. Only returned if user is authenticated with full access.

Responses

Request samples

Content type
application/json
{
  • "discord": "string",
  • "twitter": "string",
  • "github": "string",
  • "telegram": "string",
  • "seenActivity": "1713301889",
  • "readme": "string",
  • "hiddenBadges": [
    ],
  • "hiddenLists": [
    ],
  • "customPages": {
    },
  • "watchlists": {
    },
  • "profilePicUrl": "https://example.com",
  • "username": "string",
  • "profilePicImageFile": null,
  • "notifications": {
    },
  • "approvedSignInMethods": {
    },
  • "socialConntections": {
    }
}

Response samples

Content type
application/json
{ }

Miscellanous

Get Status

Gets the current status details about the blockchain / indexer (gas, block height, etc).

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication

Responses

Response samples

Content type
application/json
{
  • "status": {
    }
}

Search

Searches for collections, badges, accounts, and address lists based on the provided search value.

Authorizations:
apiKey
path Parameters
searchValue
required
string

The value to search for.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
noCollections
boolean

If true, we will skip all collection queries.
noAccounts
boolean

If true, we will skip all account queries.
noAddressLists
boolean

If true, we will skip all address list queries.
noBadges
boolean

If true, we will skip all badge queries.
specificCollectionId
any (NumberType)

If true, we will limit collection results to a single collection.

Responses

Request samples

Content type
application/json
{
  • "noCollections": true,
  • "noAccounts": true,
  • "noAddressLists": true,
  • "noBadges": true,
  • "specificCollectionId": "1"
}

Response samples

Content type
application/json
{
  • "collections": [
    ],
  • "accounts": [
    ],
  • "addressLists": [
    ],
  • "badges": [
    ]
}

Get Browse Collections

Gets details for a browse/explore page.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
object (GetBrowseCollectionsRouteRequestBody)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "collections": {
    },
  • "addressLists": {
    },
  • "profiles": {
    },
  • "activity": [
    ],
  • "badges": {
    }
}

Collections

Get Collections

Retrieves badge collections and associated details.

Authorizations:
(apiKeyuserMaybeSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "collectionsToFetch": [
    ]
}

Response samples

Content type
application/json
{
  • "collections": [
    ]
}

Get Specific Badge Owners

Retrieves the owners for a specific badge in a collection.

Authorizations:
apiKey
path Parameters
collectionId
required
integer

The numeric collection ID.
badgeId
required
integer

The numeric badge ID to retrieve owners for.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
bookmark
string

The pagination bookmark for where to start the request. Bookmarks are obtained via the previous response. "" for first request.

Responses

Request samples

Content type
application/json
{
  • "bookmark": "string"
}

Response samples

Content type
application/json
{
  • "owners": [
    ],
  • "pagination": {
    }
}

Get Badge Balances

Retrieves the balance of a specific collection for a specific address.

Authorizations:
apiKey
path Parameters
collectionId
required
integer

The ID of the collection containing the badge.
cosmosAddress
required
string

The Cosmos address for which the badge balance is to be retrieved.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
object (GetBadgeBalanceByAddressRouteRequestBody)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "balances": [
    ],
  • "incomingApprovals": [
    ],
  • "outgoingApprovals": [
    ],
  • "userPermissions": {
    },
  • "autoApproveSelfInitiatedOutgoingTransfers": true,
  • "autoApproveSelfInitiatedIncomingTransfers": true,
  • "_docId": "string",
  • "_id": "string",
  • "collectionId": "1",
  • "cosmosAddress": "cosmos1...",
  • "onChain": true,
  • "uri": "https://example.com",
  • "fetchedAt": "1713301889",
  • "fetchedAtBlock": "1",
  • "isPermanent": true,
  • "contentHash": "string",
  • "updateHistory": [
    ]
}

Get Specific Badge Activity

Retrieves the activity for a specific badge in a collection.

Authorizations:
apiKey
path Parameters
collectionId
required
integer

The ID of the collection containing the badge.
badgeId
required
integer

The ID of the badge for which activity is to be retrieved.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
bookmark
string

An optional bookmark for pagination. Bookmarks are obtained via the previous response. "" for first request.

Responses

Request samples

Content type
application/json
{
  • "bookmark": "string"
}

Response samples

Content type
application/json
{
  • "activity": [
    ],
  • "pagination": {
    }
}

Refresh Metadata

Triggers a metadata refresh for a specific collection. BitBadges API uses a refresh queue system for fetching anything off-chain. This will refetch any details for the collection (such as metadata, balances, approval details, etc). Note it will reject if recently refreshed. Uses a cooldown of 5 minutes.

Authorizations:
apiKey
path Parameters
collectionId
required
integer

The ID of the collection to trigger metadata refresh.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
object (RefreshMetadataRouteRequestBody)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Get Refresh Status

Gets the refresh status for a collection. Used to track if any errors occur during a refresh, or if it is in the queue or not.

Authorizations:
apiKey
Request Body schema: application/json
required
any (NumberType)

A numeric or stringified number. See SDK docs for NumberType conversions. Stringified numbers are used to avoid precision loss.

Responses

Request samples

Content type
application/json
"1"

Response samples

Content type
application/json
{
  • "inQueue": true,
  • "errorDocs": [
    ],
  • "refreshDoc": {
    }
}

Custom Filter Badges

Filter badges in a collection based on multiple filter values.

Authorizations:
apiKey
Request Body schema: application/json
required
collectionId
required
any (NumberType)

The collection ID to filter
Array of objects (iUintRange)

Limit to specific badge IDs. Leave undefined to not filter by badge ID.
categories
Array of strings

Limit to specific lists. Leave undefined to not filter by list.
tags
Array of strings

Limit to specific lists. Leave undefined to not filter by list.
mostViewed
string
Enum: "daily" "allTime" "weekly" "monthly" "yearly"

mostViewed is a special view that sorts by most viewed badges. May be incompatible with other filters.
bookmark
string

Pagination bookmark. Leave undefined or "" for first request.
Array of objects

Attribute queries

Responses

Request samples

Content type
application/json
{
  • "collectionId": "1",
  • "badgeIds": [
    ],
  • "categories": [
    ],
  • "tags": [
    ],
  • "mostViewed": "daily",
  • "bookmark": "string",
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "badgeIds": [
    ],
  • "pagination": {
    }
}

Claims

Complete Claim

Completes a claim for a user. This will check if the claim is valid and that all criteria is satisfied. If so, we perform the claim action.

Authorizations:
(apiKeyuserMaybeSignedIn)
path Parameters
claimId
required
string

The ID of the claim.
cosmosAddress
required
string

The Cosmos address of the user making the claim.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
prevCodesOnly
boolean

If true, we will only return the user's previous claim codes.
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "prevCodesOnly": true,
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "prevCodes": [
    ]
}

Get Claims

Retrieve claims based on the provided request body.

Authorizations:
(apiKeyuserMaybeSignedIn)
Request Body schema: application/json
required
claimIds
required
Array of strings

The claim IDs to fetch.
listId
string

If the address list is private and viewable with the link only, you must also specify the address list ID to prove knowledge of the link.

Responses

Request samples

Content type
application/json
{
  • "claimIds": [
    ],
  • "listId": "customOrReservedListId"
}

Response samples

Content type
application/json
{
  • "claims": [
    ]
}

Get External Call Key

For claim plugins that make external API calls with sensitive information, we host this route as a way of ensuring requests are actually from BitBadges. Simply specify your URL + key received, and we will return if the key is valid or not and when it was "issued". This is important to protect against man in the middle attacks.

Authorizations:
apiKey
Request Body schema: application/json
required
uri
required
string
key
required
string

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "key": "string",
  • "timestamp": 0
}

Reviews

Delete Review

Deletes a review.

Authorizations:
(apiKeyuserSignedIn)
path Parameters
reviewId
required
string

The ID of the review to be deleted.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
reviewId
required
string

The review ID to delete.

Responses

Request samples

Content type
application/json
{
  • "reviewId": "string"
}

Response samples

Content type
application/json
{ }

Add Collection Review

Adds a new review for a collection.

Authorizations:
(apiKeyuserSignedIn)
path Parameters
collectionId
required
integer

The ID of the collection for which the review is being added.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
review
required
string

The review text (1 to 2048 characters).
stars
required
any (NumberType)

The star rating (1 to 5).

Responses

Request samples

Content type
application/json
{
  • "review": "string",
  • "stars": "1"
}

Response samples

Content type
application/json
{ }

Add User Review

Adds a review for a user.

Authorizations:
(apiKeyuserSignedIn)
path Parameters
addressOrUsername
required
string

The address or username of the user for whom the review is being added.
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
review
required
string

The review text (1 to 2048 characters).
stars
required
any (NumberType)

The number of stars (1 to 5) for the review.

Responses

Request samples

Content type
application/json
{
  • "review": "string",
  • "stars": "1"
}

Response samples

Content type
application/json
{ }

API Authentication

Get Sign-In Challenge

Gets the Blockin sign-in challenge to be signed for authentication. The returned blockinMessage is the message to be signed by the user.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
chain
required
string (SupportedChain)
Enum: "Bitcoin" "Ethereum" "Cosmos" "Solana" "Unknown"

The blockchain to be signed in with.
address
required
string (NativeAddress)

The user's blockchain address. This can be their native address.
hours
any (NumberType)

The number of hours to be signed in for.

Responses

Request samples

Content type
application/json
{
  • "chain": "Bitcoin",
  • "address": "0x...",
  • "hours": "1"
}

Response samples

Content type
application/json
{
  • "nonce": "string",
  • "params": {
    },
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address...."
}

Verify Sign-In

Verifies the user-signed challenge and grants them a valid session if everything checks out.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
message
required
string (BlockinMessage)

The original Blockin message that was signed.
signature
required
string

The signature of the Blockin message
publicKey
string

Required for some chains (Cosmos) to verify signature. The public key of the signer.

Responses

Request samples

Content type
application/json
{
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "signature": "0x...",
  • "publicKey": "AksB.... (base64)"
}

Response samples

Content type
application/json
{ }

Get Sign-In Status

Checks if the user is signed in.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
object (CheckSignInStatusRequestBody)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "signedIn": true,
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "discord": {
    },
  • "twitter": {
    },
  • "github": {
    },
  • "google": {
    }
}

Sign Out

Signs the user out.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication

Responses

Response samples

Content type
application/json
{ }

Verify Sign-In (Generic)

A generic route for verifying Blockin sign-in requests. Used as a helper if implementing Blockin on your own.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
message
required
string (BlockinMessage)

The original Blockin message that was signed.
signature
required
string

The signature of the Blockin message
publicKey
string

Required for some chains (Cosmos) to verify signature. The public key of the signer.
object (VerifyChallengeOptions)

Additional options for verifying the challenge.

Responses

Request samples

Content type
application/json
{
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "signature": "0x...",
  • "publicKey": "AksB.... (base64)",
  • "options": {
    }
}

Response samples

Content type
application/json
{ }

Transactions

Broadcast Transaction

Broadcasts a transaction to the blockchain.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
One of
tx_bytes
required
any
mode
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "tx_bytes": null,
  • "mode": "string"
}

Response samples

Content type
application/json
{
  • "tx_response": {
    }
}

Simulate Transaction

Simulates a transaction on the blockchain.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
One of
tx_bytes
required
any
mode
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "tx_bytes": null,
  • "mode": "string"
}

Response samples

Content type
application/json
{
  • "gas_info": {
    },
  • "result": {
    }
}

Address Lists

Update Address Lists

Updatess address lists stored by BitBadges centralized servers.

Authorizations:
(apiKeyuserIsOwneruserSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "addressLists": [
    ]
}

Response samples

Content type
application/json
{ }

Creates Address Lists

Creates address lists stored by BitBadges centralized servers.

Authorizations:
(apiKeyuserIsOwneruserSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "addressLists": [
    ]
}

Response samples

Content type
application/json
{ }

Get Address Lists

Gets address lists. Can be on-chain or off-chain.

Authorizations:
(apiKeyuserMaybeSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
required
Array of objects

The lists and accompanyin details to fetch. Supports on-chain, off-chain, and reserved lists.

Responses

Request samples

Content type
application/json
{
  • "listsToFetch": [
    ]
}

Response samples

Content type
application/json
{
  • "addressLists": [
    ]
}

Delete Address Lists

Deletes address lists. Must be created off-chain.

Authorizations:
(apiKeyuserIsOwneruserSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
listIds
required
Array of strings

The list IDs to delete.

Responses

Request samples

Content type
application/json
{
  • "listIds": [
    ]
}

Response samples

Content type
application/json
{ }

Authentication Codes

Get Auth Code

Gets a Blockin authentication code. This is used for signing in with Blockin at in-person events. Anyone with the signature is able to fetch the preimage message.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
id
required
string

The ID of the Blockin auth code.
object (VerifyChallengeOptions)

We attempt to verify the current status with each request. You can provide additional options for verification here.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "signature": "0x...",
  • "params": {
    },
  • "cosmosAddress": "cosmos1...",
  • "verificationResponse": {
    },
  • "secretsProofs": [
    ]
}

Create Auth Code

Creates a Blockin authentication code. This is used for signing in with Blockin at in-person events.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
name
required
string

The name of the Blockin auth code for display purposes.
description
required
string

The description of the Blockin auth code for display purposes.
image
required
string

The image of the Blockin auth code for display purposes.
message
required
string (BlockinMessage)

The original Blockin message that was signed.
signature
required
string

The signature of the Blockin message
publicKey
string

The public key of the signer (if needed). Only certain chains require this.
Array of objects (iSecretsProof)

If required, you can additionally add proof of secrets to the authentication flow. This proves sensitive information (e.g. GPAs, SAT scores, etc.) without revealing the information itself.

Responses

Request samples

Content type
application/json
{
  • "name": "Name",
  • "description": "Brief description.",
  • "image": "https://example.com/image.png",
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "signature": "0x...",
  • "publicKey": "AksB.... (base64)",
  • "secretsProofs": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Delete Auth Code

Deletes a Blockin authentication code. This is used for signing in with Blockin at in-person events.

Authorizations:
(apiKeyuserSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
optional
id
required
string

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{ }

Verify Sign-In (Generic)

A generic route for verifying Blockin sign-in requests. Used as a helper if implementing Blockin on your own.

Authorizations:
apiKey
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
message
required
string (BlockinMessage)

The original Blockin message that was signed.
signature
required
string

The signature of the Blockin message
publicKey
string

Required for some chains (Cosmos) to verify signature. The public key of the signer.
object (VerifyChallengeOptions)

Additional options for verifying the challenge.

Responses

Request samples

Content type
application/json
{
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "signature": "0x...",
  • "publicKey": "AksB.... (base64)",
  • "options": {
    }
}

Response samples

Content type
application/json
{ }

Generate Auth Code Apple Wallet Pass

Generate an Apple Wallet pass based on the provided request body.

 <a
      onClick={async () => {
        const res = await BitBadgesApi.generateAppleWalletPass({
          name: authCode.name,
          description: authCode.description,
          signature: authCode.signature,
          message: createChallenge(authCode.params)
        });
        const pass = Buffer.from(res.data);

        const blob = new Blob([pass], { type: 'application/vnd.apple.pkpass' });
        const url = window.URL.createObjectURL(blob);
        if (url) {
          const link = document.createElement('a');
          link.href = url;
          link.download = 'bitbadges.pkpass';
          link.click();
        }
      }}>
      <img src="/images/add_to_apple_wallet.svg" style={{ width: 150 }} />
    </a>
Authorizations:
apiKey
Request Body schema: application/json
required
name
required
string

The name to be displayed on the pass.
description
required
string

The description to be displayed on the pass.
message
required
string (BlockinMessage)

The Blockin message of the authentication code to create the pass for.
signature
required
string

The signature of the Blockin message.

Responses

Request samples

Content type
application/json
{
  • "name": "Name",
  • "description": "Brief description.",
  • "message": "https://bitbadges.io wants you to sign in with your Cosmos address....",
  • "signature": "0x..."
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "data": "string"
}

Claim Alerts

Sends Claim Alert

Sends claim alert notifications out.

Authorizations:
(apiKeyuserSignedIn)
header Parameters
x-api-key
required
string

BitBadges API Key for authentication
Request Body schema: application/json
required
required
Array of objects

The claim alerts to send to users.

Responses

Request samples

Content type
application/json
{
  • "claimAlerts": [
    ]
}

Response samples

Content type
application/json
{ }

Get Claim Alerts

Gets claim alerts for a collection.

Authorizations:
(apiKeyuserSignedInuserIsManager)
Request Body schema: application/json
required
collectionId
required
any (NumberType)

The collection ID to get claim alerts for.
bookmark
required
string

The pagination bookmark obtained from the previous request. Leave blank for the first request.

Responses

Request samples

Content type
application/json
{
  • "collectionId": "1",
  • "bookmark": "string"
}

Response samples

Content type
application/json
{
  • "claimAlerts": [
    ],
  • "pagination": {
    }
}

Maps and Protocols

Get Follow Protocol Details

Gets the follow details for a user with the BitBadges follow protocol.

Authorizations:
apiKey
Request Body schema: application/json
required
cosmosAddress
required
string
followingBookmark
string
followersBookmark
string
protocol
string
activityBookmark
string

Responses

Request samples

Content type
application/json
{
  • "cosmosAddress": "cosmos1...",
  • "followingBookmark": "string",
  • "followersBookmark": "string",
  • "protocol": "string",
  • "activityBookmark": "string"
}

Response samples

Content type
application/json
{
  • "_docId": "string",
  • "_id": "string",
  • "cosmosAddress": "cosmos1...",
  • "followingCount": "1",
  • "followersCount": "1",
  • "followers": [
    ],
  • "following": [
    ],
  • "followingCollectionId": "1",
  • "followersPagination": {
    },
  • "followingPagination": {
    },
  • "activity": [
    ],
  • "activityPagination": {
    }
}

Get Maps

Gets maps for a collection.

Authorizations:
apiKey
Request Body schema: application/json
required
mapIds
required
Array of strings

The IDs of the maps to fetch.

Responses

Request samples

Content type
application/json
{
  • "mapIds": [
    ]
}

Response samples

Content type
application/json
{
  • "maps": [
    ]
}

Verifiable Secrets

Get Secret

Gets a secret for a collection.

Authorizations:
apiKey
Request Body schema: application/json
required
secretId
required
string

The secret ID. This is the ID that is given to the user to query the secret. Anyone with the ID can query it, so keep this safe and secure.

Responses

Request samples

Content type
application/json
{
  • "secretId": "string"
}

Response samples

Content type
application/json
{
  • "_docId": "string",
  • "_id": "string",
  • "messageFormat": "plaintext",
  • "createdBy": "cosmos1...",
  • "proofOfIssuance": {
    },
  • "secretId": "string",
  • "scheme": "bbs",
  • "type": "string",
  • "secretMessages": [
    ],
  • "dataIntegrityProof": {
    },
  • "name": "Name",
  • "image": "https://example.com/image.png",
  • "description": "Brief description.",
  • "holders": [
    ],
  • "anchors": [
    ],
  • "updateHistory": [
    ]
}

Create Secret

Creates a secret for a collection.

Authorizations:
apiKey
Request Body schema: application/json
required
required
object

Proof of issuance is used for BBS+ signatures (scheme = bbs) only. BBS+ signatures are signed with a BBS+ key pair, but you would often want the issuer to be a native address. The prooofOfIssuance establishes a link saying that "I am the issuer of this secret signed with BBS+ key pair ___".

Fields can be left blank for standard signatures.
messageFormat
required
string
Enum: "plaintext" "json"

The message format of the secretMessages.
scheme
required
string
Enum: "bbs" "standard"

The scheme of the secret. BBS+ signatures are supported and can be used where selective disclosure is a requirement. Otherwise, you can simply use your native blockchain's signature scheme.

type
required
string

The type of the secret (e.g. credential).
secretMessages
required
Array of strings

Thesse are the secrets that are signed. For BBS+ signatures, there can be >1 secretMessages, and the signer can selectively disclose the secrets. For standard signatures, there is only 1 secretMessage.

required
object

This is the signature and accompanying details of the secretMessages. The siganture maintains the integrity of the secretMessages.

This should match the expected scheme. For example, if the scheme is BBS+, the signature should be a BBS+ signature and signer should be a BBS+ public key.

name
required
string

Metadata for the secret for display purposes. Note this should not contain anything sensitive. It may be displayed to verifiers.

image
required
string

Metadata for the secret for display purposes. Note this should not contain anything sensitive. It may be displayed to verifiers.

description
required
string

Metadata for the secret for display purposes. Note this should not contain anything sensitive. It may be displayed to verifiers.

Responses

Request samples

Content type
application/json
{
  • "proofOfIssuance": {
    },
  • "messageFormat": "plaintext",
  • "scheme": "bbs",
  • "type": "string",
  • "secretMessages": [
    ],
  • "dataIntegrityProof": {
    },
  • "name": "Name",
  • "image": "https://example.com/image.png",
  • "description": "Brief description."
}

Response samples

Content type
application/json
{
  • "secretId": "string"
}

Update Secret

Updates a secret for a collection.

Authorizations:
apiKey
Request Body schema: application/json
required
secretId
required
string

The secret ID. This is the ID that is given to the user to query the secret. Anyone with the ID can query it, so keep this safe and secure.

Array of objects

You can approve specific holders to view the secret.
Array of objects

Blockchain anchors to add to the secret. These are on-chain transactions that can be used to prove stuff about the secret, like existence at a certain point in time or to maintain data integrity.

object

Proof of issuance is used for BBS+ signatures (scheme = bbs) only. BBS+ signatures are signed with a BBS+ key pair, but you would often want the issuer to be a native address. The prooofOfIssuance establishes a link saying that "I am the issuer of this secret signed with BBS+ key pair ___".

Fields can be left blank for standard signatures.
messageFormat
string
Enum: "plaintext" "json"

The message format of the secretMessages.
scheme
string
Enum: "bbs" "standard"

The scheme of the secret. BBS+ signatures are supported and can be used where selective disclosure is a requirement. Otherwise, you can simply use your native blockchain's signature scheme.

type
string

The type of the secret (e.g. credential).
secretMessages
Array of strings

Thesse are the secrets that are signed. For BBS+ signatures, there can be >1 secretMessages, and the signer can selectively disclose the secrets. For standard signatures, there is only 1 secretMessage.

object

This is the signature and accompanying details of the secretMessages. The siganture maintains the integrity of the secretMessages.

This should match the expected scheme. For example, if the scheme is BBS+, the signature should be a BBS+ signature and signer should be a BBS+ public key.

name
string

Metadata for the secret for display purposes. Note this should not contain anything sensitive. It may be displayed to verifiers.

image
string

Metadata for the secret for display purposes. Note this should not contain anything sensitive. It may be displayed to verifiers.

description
string

Metadata for the secret for display purposes. Note this should not contain anything sensitive. It may be displayed to verifiers.

Responses

Request samples

Content type
application/json
{
  • "secretId": "string",
  • "holdersToSet": [
    ],
  • "anchorsToAdd": [
    ],
  • "proofOfIssuance": {
    },
  • "messageFormat": "plaintext",
  • "scheme": "bbs",
  • "type": "string",
  • "secretMessages": [
    ],
  • "dataIntegrityProof": {
    },
  • "name": "Name",
  • "image": "https://example.com/image.png",
  • "description": "Brief description."
}

Response samples

Content type
application/json
{ }

Delete Secret

Deletes a secret for a collection.

Authorizations:
apiKey
Request Body schema: application/json
required
secretId
required
string

The secret ID. This is the ID that is given to the user to query the secret. Anyone with the ID can query it, so keep this safe and secure.

Responses

Request samples

Content type
application/json
{
  • "secretId": "string"
}

Response samples

Content type
application/json
{ }