API keys

API keys are created in your dashboard and are only shown once. The API never returns key secrets — these endpoints are metadata-only.

The API key model

API keys are scoped. Create a separate key per integration and only grant what it needs.

Properties

Name

id

Type

integer

Description

Unique identifier for the API key (metadata record).
Name

name

Type

string

Description

Human label you set in Settings → Integrations.
Name

scopes

Type

string[]

Description

Granted scopes for this key (least-privilege).
Name

created_at

Type

timestamp

Description

Timestamp of when the key was created.
Name

last_used_at

Type

timestamp | null

Description

Timestamp of the last API request using this key.
Name

revoked_at

Type

timestamp | null

Description

Timestamp of when the key was revoked (if revoked).

GET/v1/api-keys/

List API keys

This endpoint returns API key metadata only. For security reasons, key secrets are never returned by the API.

Required scope

read:api_keys

Request

GET

/v1/api-keys/

curl -G https://api.twentybaan.com/v1/api-keys/ \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d limit=10

GET

/v1/api-keys/

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/api-keys/");
url.searchParams.set("limit", "10");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

GET

/v1/api-keys/

type TwentybaanApiKey = {
  id: number;
  name: string;
  scopes: string[];
  created_at: string;
  last_used_at: string | null;
  revoked_at: string | null;
};

type TwentybaanApiKeysResponse =
  | { ok: true; items: TwentybaanApiKey[]; next_before_id: number | null }
  | { ok: false; error: string };

const token = process.env.TWENTYBAAN_API_KEY!;

const url = new URL("https://api.twentybaan.com/v1/api-keys/");
url.searchParams.set("limit", "10");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const data = (await res.json()) as TwentybaanApiKeysResponse;
if (!res.ok || !data.ok) throw new Error("Request failed");

console.log(data.items);

GET

/v1/api-keys/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

res = requests.get(
  "https://api.twentybaan.com/v1/api-keys/",
  headers={
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
  },
  params={"limit": 10},
  timeout=30,
)
res.raise_for_status()
print(res.json())

GET

/v1/api-keys/

<?php

$token = getenv('TWENTYBAAN_API_KEY') ?: '';

$url = "https://api.twentybaan.com/v1/api-keys/" . '?' . http_build_query(['limit' => 10]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer " . $token,
  ],
]);

$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n";
echo $body;

GET

/v1/api-keys/

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("TWENTYBAAN_API_KEY") ?? "";

var url = "https://api.twentybaan.com/v1/api-keys/?limit=10";

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var res = await client.GetAsync(url);
var body = await res.Content.ReadAsStringAsync();

Console.WriteLine((int)res.StatusCode);
Console.WriteLine(body);

GET

/v1/api-keys/

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/api-keys/")
uri.query = URI.encode_www_form({ limit: 10 })

req = Net::HTTP::Get.new(uri)
req["Accept"] = "application/json"
req["Authorization"] = "Bearer #{token}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts res.code
puts res.body

GET

/v1/api-keys/

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  token := os.Getenv("TWENTYBAAN_API_KEY")

  u, err := url.Parse("https://api.twentybaan.com/v1/api-keys/")
  if err != nil {
    panic(err)
  }

  q := u.Query()
  q.Set("limit", "10")
  u.RawQuery = q.Encode()

  req, err := http.NewRequest("GET", u.String(), nil)
  if err != nil {
    panic(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Authorization", "Bearer "+token)

  client := &http.Client{Timeout: 30 * time.Second}
  res, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)
  fmt.Println(res.Status)
  fmt.Println(string(body))
}

Response

{
  "ok": true,
  "items": [
    {
      "id": 123,
      "name": "CRM sync key",
      "scopes": ["read:me", "read:listings", "read:contact_messages"],
      "created_at": "2026-01-12T08:00:00Z",
      "last_used_at": "2026-01-12T09:10:00Z",
      "revoked_at": null
    }
  ],
  "next_before_id": null
}

GET/v1/api-keys/?id=:id

Retrieve an API key

Fetch a single API key metadata record by id.

Required scope

read:api_keys

Request

GET

/v1/api-keys/?id=123

curl -G https://api.twentybaan.com/v1/api-keys/ \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id=123

GET

/v1/api-keys/?id=123

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/api-keys/");
url.searchParams.set("id", "123");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

GET

/v1/api-keys/?id=123

type TwentybaanApiKey = {
  id: number;
  name: string;
  scopes: string[];
  created_at: string;
  last_used_at: string | null;
  revoked_at: string | null;
};

type TwentybaanApiKeyResponse =
  | { ok: true; api_key: TwentybaanApiKey }
  | { ok: false; error: string };

const token = process.env.TWENTYBAAN_API_KEY!;

const url = new URL("https://api.twentybaan.com/v1/api-keys/");
url.searchParams.set("id", "123");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const data = (await res.json()) as TwentybaanApiKeyResponse;
if (!res.ok || !data.ok) throw new Error("Request failed");

console.log(data.api_key);

GET

/v1/api-keys/?id=123

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

res = requests.get(
  "https://api.twentybaan.com/v1/api-keys/",
  headers={
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
  },
  params={"id": 123},
  timeout=30,
)
res.raise_for_status()
print(res.json())

GET

/v1/api-keys/?id=123

<?php

$token = getenv('TWENTYBAAN_API_KEY') ?: '';

$url = "https://api.twentybaan.com/v1/api-keys/" . '?' . http_build_query(['id' => 123]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer " . $token,
  ],
]);

$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n";
echo $body;

GET

/v1/api-keys/?id=123

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("TWENTYBAAN_API_KEY") ?? "";

var url = "https://api.twentybaan.com/v1/api-keys/?id=123";

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var res = await client.GetAsync(url);
var body = await res.Content.ReadAsStringAsync();

Console.WriteLine((int)res.StatusCode);
Console.WriteLine(body);

GET

/v1/api-keys/?id=123

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/api-keys/")
uri.query = URI.encode_www_form({ id: 123 })

req = Net::HTTP::Get.new(uri)
req["Accept"] = "application/json"
req["Authorization"] = "Bearer #{token}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts res.code
puts res.body

GET

/v1/api-keys/?id=123

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  token := os.Getenv("TWENTYBAAN_API_KEY")

  u, err := url.Parse("https://api.twentybaan.com/v1/api-keys/")
  if err != nil {
    panic(err)
  }

  q := u.Query()
  q.Set("id", "123")
  u.RawQuery = q.Encode()

  req, err := http.NewRequest("GET", u.String(), nil)
  if err != nil {
    panic(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Authorization", "Bearer "+token)

  client := &http.Client{Timeout: 30 * time.Second}
  res, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)
  fmt.Println(res.Status)
  fmt.Println(string(body))
}

Response

{
  "ok": true,
  "api_key": {
    "id": 123,
    "name": "CRM sync key",
    "scopes": ["read:me", "read:listings", "read:contact_messages"],
    "created_at": "2026-01-12T08:00:00Z",
    "last_used_at": "2026-01-12T09:10:00Z",
    "revoked_at": null
  }
}