Authenticating with Numbers Station

We've tried to make it as easy as possible to authenticate with the Numbers Station API. Please let us know if you have a specific authentication method you would like to see supported!

Overview

All authentication methods create a session in the Numbers Station API. However, you can choose the medium to pass credentials that best suits your application. Specifically you can user either cookies or bearer tokens with each having its own use and limitations.

Cookie-Based Authentication

Cookie-based authentication is typically simpler to implement and more secure than bearer tokens. However, it is not as flexible especially when it comes to third-party applications. In order for this to work as a third-party, we will need to set the SameSite=None attribute on the cookie. All endpoints expose a third_party parameter that should be set to true when making requests.

Additionally, the Numbers Station API employs middleware to block CORS requests from domains that have not been specifically allowlisted. If you'd like to deploy a client of the Numbers Station API, you must provide us with a list of domains we must add to our allowlist. Please contact support for assistance. We have allowlisted localhost:3000 to allow for local development.

Native

Native authentication employs our in-house authentication server which relies on the username and password of the user. With those credentials we return a cookie which is included in all subsequent requests to the API.

Example javascript code to authenticate with the Numbers Station API that you can run in your browser's console from localhost:3000:

// Login to the endpoint w/ third_party=true
const formData = new FormData();
formData.append("username", YOUR_USERNAME);
formData.append("password", YOUR_PASSWORD);
const login_url = "https://api.numbersstation.ai/api/v1/login/session?third_party=true";
await fetch(login_url, {
    "credentials": "include",
    "body": formData,
    "method": "POST"
});


// Then all subsequent requests to api.numbersstation.ai will have the correct
// Cookie header set. 
// For example, you can read the current user like so:
await fetch(`https://api.numbersstation.ai/api/v3/orgs/${YOUR_ACCOUNT_NAME}/users/me`, {
    "credentials": "include"
});

OAuth2

OAuth2 is a popular authorization method that can be used to authenticate with the Numbers Station API. We support the PKCE grant type. Currently our public cloud supports authentication with Google. The simplest version of this is merely a login with Google button like so:

<a href="https://api.numbersstation.ai/api/v1/login/session/oauth?provider=google&redirect_header=true&redirect_uri={URL}&third_party=true">
    Login with Google
</a>

However, if you want to control the redirect, you can also set redirect_header=false and handle the redirect yourself. In this case, the redirect URL is set as the body of the response. Remember to a set a redirect_uri parameter in the query string of the URL. This should typically be the URL of your application.

To authenticate with OAuth2 using a different provider, you will need to provide us with a client ID and a redirect URI. Please contact support for assistance.

Bearer Token Authentication

Bearer token authentication is more flexible than cookie-based authentication, but it is important to keep the token secure. You'll also need to include the token in the Authorization header of all requests to the Numbers Station API.

Native

Native authentication employs our in-house authentication server which relies on the username and password of the user. With those credentials we return a bearer token which must be included in all subsequent requests to the API.

Example javascript code to authenticate with the Numbers Station API that you can run in your browser's console from localhost:3000:

// Login to the endpoint w/ third_party=true
const formData = new FormData();
formData.append("username", YOUR_USERNAME);
formData.append("password", YOUR_PASSWORD);
const login_url = "https://api.numbersstation.ai/api/v1/login/access-token";
const response = await fetch(login_url, {
    "body": formData,
    "method": "POST"
});
const data = await response.json();
const token = data.access_token;

// Then we must include the token in all subsequent requests to the API.
// For example, you can read the current user like so:
await fetch(`https://api.numbersstation.ai/api/v3/orgs/${YOUR_ACCOUNT_NAME}/users/me`, {
    "headers": {
        "Authorization": `Bearer ${token}`
    }
});

API Key

API key authentication is the perfect solution for server-to-server communication. You can generate an API key from the settings page of your Numbers Station account. This key can then be used to get a bearer token which must be included in all subsequent requests to the API.

Danger

Do not expose your API key in client-side code or it could result in unauthorized access of your account.

Example javascript code to authenticate with the Numbers Station API that you can run in your browser's console from localhost:3000:

// Get a bearer token from the API key
const user_email = EMAIL_OF_USER_IN_ACCOUNT;
const account_name = NAME_OF_ACCOUNT;
const login_url = `https://api.numbersstation.ai/api/v1/login/access-token/api-key?email=${user_email}&account_name=${account_name}`;
const response = await fetch(login_url, {
    "headers": {
        "X-API-Key": YOUR_API_KEY
    },
    "method": "POST"
});
const data = await response.json();
const token = data.access_token;

// Then we must include the token in all subsequent requests to the API.
// For example, you can read the current user like so:
await fetch(`https://api.numbersstation.ai/api/v3/orgs/${account_name}/users/me`, {
    "headers": {
        "Authorization": `Bearer ${token}`
    }
});