Getting started
Accounts and API keys
Your app authenticates with an API key. The easiest way to manage keys is the API keys page of your dashboard. The calls below do the same thing, for when you want to automate it.
Using a key
Send the key in the Authorization header of every API request:
Authorization: Bearer rn_live_qb3tqt2dfhbn_…A missing or invalid key returns 401 unauthenticated. A key without the right scope returns 403 insufficient_scope.
Creating a key
Creating a key takes three things: the session cookie from signing in, the csrf_token from the same response, and your password again, because a key is a long-lived credential.
<?php
$api = getenv('RASTERNIVO_API_URL') ?: 'https://rasternivo-api.swiftinfocorp.com/v1';
$email = getenv('RASTERNIVO_EMAIL');
$password = getenv('RASTERNIVO_PASSWORD');
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_COOKIEFILE => '', // keep the session cookie between the two requests
]);
// 1. Sign in
curl_setopt_array($ch, [
CURLOPT_URL => "$api/auth/login",
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['email' => $email, 'password' => $password]),
]);
$login = json_decode(curl_exec($ch), true);
// 2. Create the key
curl_setopt_array($ch, [
CURLOPT_URL => "$api/api-keys",
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-CSRF-Token: ' . $login['csrf_token']],
CURLOPT_POSTFIELDS => json_encode([
'label' => 'my-server',
'scopes' => ['conversions:read', 'conversions:write', 'usage:read'],
'password' => $password, // asked again because a key is a long-lived credential
]),
]);
$key = json_decode(curl_exec($ch), true);
echo $key['secret'], "\n"; // shown only once: store it safelyimport os
import requests
API = os.environ.get("RASTERNIVO_API_URL", "https://rasternivo-api.swiftinfocorp.com/v1")
email = os.environ["RASTERNIVO_EMAIL"]
password = os.environ["RASTERNIVO_PASSWORD"]
session = requests.Session() # keeps the session cookie between requests
# 1. Sign in
login = session.post(f"{API}/auth/login", json={"email": email, "password": password})
login.raise_for_status()
# 2. Create the key
r = session.post(
f"{API}/api-keys",
headers={"X-CSRF-Token": login.json()["csrf_token"]},
json={
"label": "my-server",
"scopes": ["conversions:read", "conversions:write", "usage:read"],
"password": password, # asked again because a key is a long-lived credential
},
)
r.raise_for_status()
print(r.json()["secret"]) # shown only once: store it safelyconst API = process.env.RASTERNIVO_API_URL ?? "https://rasternivo-api.swiftinfocorp.com/v1";
const email = process.env.RASTERNIVO_EMAIL;
const password = process.env.RASTERNIVO_PASSWORD;
// 1. Sign in
const login = await fetch(`${API}/auth/login`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password }),
});
if (!login.ok) throw new Error(await login.text());
const { csrf_token } = await login.json();
const cookie = login.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
// 2. Create the key
const res = await fetch(`${API}/api-keys`, {
method: "POST",
headers: { "Content-Type": "application/json", "X-CSRF-Token": csrf_token, Cookie: cookie },
body: JSON.stringify({
label: "my-server",
scopes: ["conversions:read", "conversions:write", "usage:read"],
password, // asked again because a key is a long-lived credential
}),
});
if (!res.ok) throw new Error(await res.text());
console.log((await res.json()).secret); // shown only once: store it safelyAPI="https://rasternivo-api.swiftinfocorp.com/v1"
# 1. Sign in. The cookie is saved to session.txt; copy csrf_token from the response.
curl -c session.txt -X POST "$API/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "your-password"}'
# 2. Create the key, sending the cookie, the CSRF token and your password again.
curl -b session.txt -X POST "$API/api-keys" \
-H "Content-Type: application/json" \
-H "X-CSRF-Token: CSRF_TOKEN_FROM_STEP_1" \
-d '{"label": "my-server",
"scopes": ["conversions:read", "conversions:write", "usage:read"],
"password": "your-password"}'Your account must be verified first. A wrong password returns 401 reauthentication_required.
Scopes
Give each key only what it needs. A reporting script, for example, only needs usage:read.
| Scope | Allows |
|---|---|
conversions:write | Create and cancel conversions |
conversions:read | List conversions, read their status and get download links |
usage:read | Read the plan, credits, limits and credit log |
Listing and revoking keys
These calls use the same session as creating a key. DELETE also needs the X-CSRF-Token header. Revoking takes effect immediately.
curl -b session.txt "https://rasternivo-api.swiftinfocorp.com/v1/api-keys"
curl -b session.txt -X DELETE "https://rasternivo-api.swiftinfocorp.com/v1/api-keys/KEY_ID" \
-H "X-CSRF-Token: CSRF_TOKEN"The list shows each key's prefix, label, scopes and when it was last used, never the secret. A workspace can have up to 25 active keys.
Keeping keys safe
- Keep keys on your server. Never put them in a web page, a mobile app or a public repository.
- Load them from environment variables or a secrets manager, not from your code.
- Use a separate key for each app or environment, so you can revoke one without affecting the others.
- We store only a hash, so a lost key can't be recovered. Revoke it and create a new one. To replace a key without downtime, create the new key, switch your app to it, then revoke the old one.
- If a key may have leaked, revoke it straight away.
Account calls
| Call | What it does |
|---|---|
POST /v1/auth/register | Create an account: {email, password, accept_terms}. Passwords need at least 10 characters. |
POST /v1/auth/verify-email | Confirm the address with the emailed {token}. This starts the trial. |
POST /v1/auth/resend-verification | Send the verification email again: {email} |
POST /v1/auth/login | Sign in. Sets the session cookie and returns {account, csrf_token}. |
POST /v1/auth/logout | Sign out |
POST /v1/auth/password-reset/request | Email a reset link: {email} |
POST /v1/auth/password-reset/confirm | Set a new password: {token, new_password}. Signs out all your sessions. |
Signed-in requests that change something (POST, PUT, DELETE) must send the X-CSRF-Token header. Sign-up and sign-in attempts are rate limited; see Limits.