OAuth

Once per app, unauthenticated. The answer carries your rkoc_ client id and a rkor_ registration access token, shown exactly once — it is the only credential that can read, replace or delete the client later.

curl -X POST "https://api.rasket.com/oauth/register" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "client_name": "Acme Invoices",
  "redirect_uris": ["https://invoices.acme.example/rasket/callback"],
  "scope": "emails:send emails:read"
}'

const response = await fetch("https://api.rasket.com/oauth/register", {
  method: "POST",
  headers: {
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    client_name: "Acme Invoices",
    redirect_uris: ["https://invoices.acme.example/rasket/callback"],
    scope: "emails:send emails:read"
  }),
});

const data = await response.json();

import os

import requests

response = requests.post(
    "https://api.rasket.com/oauth/register",
    headers={
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "client_name": "Acme Invoices",
    "redirect_uris": ["https://invoices.acme.example/rasket/callback"],
    "scope": "emails:send emails:read"
  },
)

print(response.json())

A fresh random verifier for every authorization, and its SHA-256 hash as the challenge. The method is S256; plain is refused.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(16).toString("base64url");

// Keep verifier and state in the person's session until the browser comes back.

Open this URL in their browser. They sign in, choose one team, and approve the scopes you asked for.

https://api.rasket.com/oauth/authorize?response_type=code&client_id=rkoc_7Fq2Lm9pXw3Kd8Vn1Zt5Rb4C&redirect_uri=https%3A%2F%2Finvoices.acme.example%2Frasket%2Fcallback&scope=emails%3Asend+emails%3Aread&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

The browser comes back to your redirect URI with a code and your state:

https://invoices.acme.example/rasket/callback?code=rkc_…&state=af0ifjsldkj

Check that state is the one you stored before doing anything else. A refusal comes back the same way with error=access_denied.

Within 10 minutes, with the verifier from step 2 and the same redirect URI. The code works once.

curl -X POST "https://api.rasket.com/oauth/token" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "authorization_code",
  "client_id": "rkoc_7Fq2Lm9pXw3Kd8Vn1Zt5Rb4C",
  "code": "rkc_…",
  "redirect_uri": "https://invoices.acme.example/rasket/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}'

const response = await fetch("https://api.rasket.com/oauth/token", {
  method: "POST",
  headers: {
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_type: "authorization_code",
    client_id: "rkoc_7Fq2Lm9pXw3Kd8Vn1Zt5Rb4C",
    code: "rkc_…",
    redirect_uri: "https://invoices.acme.example/rasket/callback",
    code_verifier: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }),
});

const data = await response.json();

import os

import requests

response = requests.post(
    "https://api.rasket.com/oauth/token",
    headers={
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "grant_type": "authorization_code",
    "client_id": "rkoc_7Fq2Lm9pXw3Kd8Vn1Zt5Rb4C",
    "code": "rkc_…",
    "redirect_uri": "https://invoices.acme.example/rasket/callback",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  },
)

print(response.json())

The token endpoint also accepts application/x-www-form-urlencoded, which is what a conforming OAuth client sends.

The access token goes where an API key goes, and every endpoint its scopes reach answers exactly as it would to a key. There is no team parameter: the token already belongs to the team the person chose.

POST https://api.rasket.com/emails
Authorization: Bearer rko_…
User-Agent: acme-billing/1.0
Content-Type: application/json

• A scope the grant does not hold is 403 invalid_permission, with WWW-Authenticate: Bearer error="insufficient_scope", naming the scope needed when there is one.
• An expired or revoked token is 401 missing_api_key. Refresh, or send the person through authorize again.

An access token lasts 1 hour. Trade the refresh token for a new pair, and store the new refresh token: the one you presented stops working at that moment.

POST https://api.rasket.com/oauth/token
User-Agent: acme-billing/1.0
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=rkoc_7Fq2Lm9pXw3Kd8Vn1Zt5Rb4C&refresh_token=rkr_…

Present an old refresh token again and the whole grant is revoked, every token under it with it. That is how a stolen refresh token is caught — so a client that retries a refresh with the token it already spent will lock itself out.

A refresh may ask for a narrower scope, never a wider one. However often you refresh, the chain ends 90 days after the code was first exchanged; then the person approves again.

When the person signs out of your app, send the refresh token to POST /oauth/revoke: it and every access token of the grant stop working. The team's own switch is bigger — revoking the grant, from Connected apps in the dashboard or with DELETE /oauth/grants/{oauth_grant_id}, disconnects your app entirely.