API Reference

Getting Started

Authentication

Authentication with Parasol API is supports the following two scenarios

  1. Organization Management: Managing member, organization, and organization members
  2. User Asset Management: Managing users, collections and items

Organization Management

In order to start using the Parasol API, you need to first register the following entities

  • Member - this represents your user management with Parasol.
    • You create an member account with POST /members
  • Organization - this represents your organization account within Parasol
    • You create an organization with POST /organizations, this requires JWT token
  • Organization Membership - this defines the different roles members can have within an organization
    • You invite other members to your organization with POST /organizations/:organizationId/members, this requires JWT token

In order to get a JWT token, after creating a member, you need to login with POST /member/logins

Users Asset Management

After you've created an organization, you can register Apps and provision API keys

  • App - this is the entity that will namespace your users, items, and collections
    • You create an app with POST /apps, this requires JWT token
  • API key - this is the secret token that will be used for server to server communication between your server and Parasol APIs
    • You create an app with POST /apps/:appId/keys, this requires JWT token

Please be sure to vault the token generated from API key creation into a secure location that's only accessible within a private network by your backend services. The API key will be used to manage users, collections, and items associated with your app and organization

Error Codes

HTTP Status Codes

The following is a list of HTTP status codes that can be returned across our API endpoints

400 - Bad Request

  • Request payload is invalid

401 - Unauthorized

  • Access token is invalid or not provided on a protected endpoint

404 - Not Found

  • Requested resource does not exist

500 - Internal Server Error

  • General unhandled problem within application

Application Error Codes

Within 4XX or 500 HTTP status codes, the Parasol API also returns specific application error codes to provide on where the errors originated from and for more granular description of the errors themselves.

App

  • 101 API not found
  • 102 API Key not found

Item

  • 200: Internal Server error
  • 201: item not found
  • 202: token id must be provided for all or none of the items
  • 203: too many items in one batch
  • 204: collection reached total supply limit
  • 205: items must have consecutive token ids
  • 206: incorrect secret
  • 207: sticker collection is missing a required attribute
  • 208: collection is not mintable at the moment

Collection

  • 300: Internal server error
  • 301: collection not found

Organization

  • 401: Organization not found
  • 402 Membership not found
  • 403 Member not found