Quick Start Guide

Creating your user

To have your user created, you can either contact the Tiber team or you can make a request to the sign-up endpoint with your email and password. Throughout this docsite, we will use localhost:3000 in place of a deployed domain.

fetch('http://localhost:3000/api/auth/sign-up/email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '',
    email: '',
    password: '',
  })
})

The name you provide will be used to keep track of your user. Passwords must be at least 8 characters.

Confirm your email and upgrade to admin

Your user account will require email confirmation. Additionally, only admin users are authorized to access backend APIs and other developer tools, so you must request that your user be upgraded to admin.

Creating an API Key

Sign in

Once you've been assigned a user and verified your email, you can use your email and password to generate an API key. First, sign in to get session cookies for authentication. Store the cookies for later use:

const signInResponse = await fetch('http://localhost:3000/api/auth/sign-in/email', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
    email: '',
    password: '',
	})
});

const sessionCookies = signInResponse.headers.getSetCookie()[0];

Generate an API key

Next, call the create API Key endpoint to create a key. Using the session cookies, issue a POST request to the /api/auth/api-key/create endpoint.

Upon creation of the API key, you will receive the key value. It will only be shown to you once, upon successful key creation. Make sure to store the key's id and key fields in a secure location. The key will be passed in the headers of future API calls for authentication, and the id is useful for retrieval or making changes to your API key, such as disabling/enabling it, rate limiting, and key expiration.

const apiKeyResponse = await fetch('http://localhost:3000/api/auth/api-key/create', {
	method: 'POST',
	headers: {
		'Content-Type': "application/json",
		'Cookie': sessionCookies,
	},
	body: JSON.stringify({
		name: "name-of-api-key"
	}),
});

//retrieve id and key value from response
const apiKeyJson = await apiKeyResponse.json();
const id = apiKeyJson.id;
const key = apiKeyJson.key;
console.log(id, key); //store these values in a secure location

In addition to the name of the key, you can optionally pass an expiration period in the request body. Measured in seconds, the "expiresIn" field defines the duration of the key. If no value is passed, the API key will not expire. New request JSON example:

{
	"name": "name-of-api-key",
	"expiresIn": 60 * 60 * 24 * 7, //1 week duration
}

Get an organization id

All API request are performed within the context of a particular organization, so Caddie will check all requests for two headers:

• X-API-KEY: used for authentication
• X-ORGANIZATION-ID: used to identify the organization within which a request is being made

If you don't have any organizations, you can create one. If you are creating your first organization, we recommend you name this something that communicates the fact that it's a utility/admin organization, used primarily for your admin user. You can always create more organizations as needed.

fetch('http://localhost:3000/api/auth/organization/create', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'Cookies': sessionCookies
	},
	body: JSON.stringify({
	    name: 'Organization Name',
	    slug: 'org-slug',
  })
})

The "slug" is a short identifier for the organization and should be set to a short, dash-separated version of the organization name.

Once you have gotten your API key and organization id, you can make requests in the style of this template GET request:

GET /api/endpoint HTTP/1.1
Host: localhost:3000
X-API-KEY: your-api-key
X-ORGANIZATION-ID: your-organization-id