Carbon

Documentation

Welcome to Carbon's docs!

Get Started    

Authentication API

const axios = require("axios");
const ROOT = process.env.NODE_ENV === "PRODUCTION" ? "https://api.carbon.money" : "https://sandbox.carbon.money";

Introduction

Our API uses JSON Web Tokens, JWT's, to authenticate superusers. Most endpoints (apart from creating superusers) will require superuser authentication. Contacts need to have their uuid's passed in as either a request body param or query param to authenticate. For more on what superusers or contacts are, check out this

Superuser Registration Update

Go to www.carbon.money and click on 'Dashboard' at the top right. There you can create your developer account, access your credentials, view metrics, review transaction reporting, compare our fees versus your set fees, and manage fee/loan settlement! For more on our dashboard check out this article. We no longer recommend creating superusers via our API and have removed all documentation referencing this functionality.

Sandbox accounts are auto-approved by our API so you can start testing integration in sandbox right away. When you are ready to go live in production reach out to team at carbon.money and also click here.

What are JWTs?

JWT (JSON Web Tokens) are used to authenticate user credentials. More information can be found at www.jwt.io.

Sandbox vs Production Super Users

Sandbox and Production are two different databases. As such, super users on sandbox are different from super users on production.

After creating a developer account, you can access your API keys by clicking on the 'Developers' tab and then clicking on the 'API KEY' section. You will have both sandbox and production superuser credentials.

Your production user API key needs to be approved before you can go live.

To get production access, see Going Live.

Legacy API Key v Secret Key

Note that your superuser UUID is your legacy API key used to obtain your JWT. You will also have a public key and secret key for the production and sandbox environments. You can use your secret key in place of your JWT to authenticate via the same header format (more on that below). While JWTs have indefinite lifetimes for usage, secret keys have permanent usage. In v2 of our API, we will deprecate the legacy API key / superuser UUID and JWTs. And we will only enable secret key authentication / public key authentication for enhanced security. If you are using legacy auth, please migrate soon!

Your secret key and public keys can be accessed from your Dashboard account.

Secret key authentication will by and large replace legacy authentication via your JWT. Public key authentication is used for some new products such as the payment gateway to non-sensitively identify superusers.

Webhook Secret

If you plan on building using Fiber's API, please save your webhookSecret. This is very important for setting up webhook listeners for events and verifying incoming POST calls. If you can't access your webhook secret after creating a developer account, reach out to daniel at carbon.money and gavin at carbon.money.

Retrieve Existing User JWT (LEGACY)

To obtain an existing user's JWT, use the following route. You need to pass in your API key (uuid). You can also obtain via the dashboard as detailed above.

let url = `${ROOT}/v1/users/returnJWT?apikey=942a8e0a-78b8-4cd1-a963-49c3d7e7e570`;

axios.get(url).then(result => console.log).catch(err => console.log);
{
    message: "success",
    jwtToken: jwtToken,
    approved: false,
    country: "RU",
    ip: "0.0.0.0"
}
// 404
{
    message: 'User not found',
    code: 404
}

// 500
{
    message: 'Internal server error',
    code: 500
}

You must pass this header in most if not all API calls for Carbon. This is your way of authenticating an API call.

Authenticating a request as a Super

// legacy. will be deprecated in v2
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';

let headers = {
  headers: {
    Authorization: `Bearer ${jwtToken}`
  }
}

// secret key (recommended)
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';

let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
};
// 401
{
  message: 'Unauthorized superuser jwt',
  code: 401
}

//403 
{
  message: 'Unapproved Super. Please contact Carbon to approve',
  code: 403
}

Email Notifications

Some users may prefer to notify their contacts directly. By default, Carbon sends email notifications for successful purchases. You can toggle this feature here.

Pass in status as a boolean for the request.

// legacy auth that will be deprecated in our v2 api
/*
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';
*/
// we strongly recommend using your secret key to more securely authenticate your superuser instead
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';

let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
};

let url = `${ROOT}/v1/users/emailNotification`;

let data = {
  status: false 	// false to turn off notification, true to turn on
}

axios.post(url, data, header).then(result => console.log(result)).catch(err => console.log(err));
{ 
	message: "successfully updated email notification status to false"
}
// 401
{
  message: 'status must be a boolean',
  code: 401
}
Thank you for your feedback

Updated 2 months ago


Authentication API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.