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 safely
import 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 safely
const 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 safely
API="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.

ScopeAllows
conversions:writeCreate and cancel conversions
conversions:readList conversions, read their status and get download links
usage:readRead 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

CallWhat it does
POST /v1/auth/registerCreate an account: {email, password, accept_terms}. Passwords need at least 10 characters.
POST /v1/auth/verify-emailConfirm the address with the emailed {token}. This starts the trial.
POST /v1/auth/resend-verificationSend the verification email again: {email}
POST /v1/auth/loginSign in. Sets the session cookie and returns {account, csrf_token}.
POST /v1/auth/logoutSign out
POST /v1/auth/password-reset/requestEmail a reset link: {email}
POST /v1/auth/password-reset/confirmSet 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.