Skip to main content
GET
/
v1
/
scopes
List Scopes
curl --request GET \
  --url https://api.truthlocks.com/v1/scopes \
  --header 'X-API-Key: <api-key>'
import requests

url = "https://api.truthlocks.com/v1/scopes"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.truthlocks.com/v1/scopes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/scopes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/scopes"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.truthlocks.com/v1/scopes")
  .header("X-API-Key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/scopes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "scope": "<string>",
    "resource": "<string>",
    "action": "<string>",
    "display_name": "<string>",
    "description": "<string>",
    "category": "<string>",
    "is_builtin": true,
    "created_at": "2023-11-07T05:31:56Z"
  }
]
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

​
List Scopes

GET /v1/scopes Returns all permission scopes available to the authenticated tenant. This includes platform-defined built-in scopes and any custom scopes created by the tenant. Scopes follow the resource:action format defined by the MAIP protocol.

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Query Parameters

​
category
string
Filter scopes by category. One of: "data", "model", "tool", "agent", "admin", "receipt", "custom". Omit to return all categories.

​
Response

Returns an array of scope definition objects.
​
id
string
UUID of the scope definition.
​
tenant_id
string
UUID of the tenant that owns this scope. null for platform-level built-in scopes.
​
scope
string
The full scope string in resource:action format (e.g., "data:read", "model:train").
​
resource
string
The resource component of the scope (e.g., "data", "model", "tool").
​
action
string
The action component of the scope (e.g., "read", "write", "*").
​
display_name
string
Human-readable name for the scope.
​
description
string
Detailed description of what the scope grants access to.
​
category
string
Scope category for organizational purposes.
​
is_builtin
boolean
true for platform-defined scopes, false for tenant-created custom scopes.
​
created_at
string
ISO 8601 creation timestamp.

​
Example

curl -G https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: tl_live_..." \
  -d "category=data"

​
Built-in Scope Categories

The platform provides 25+ built-in scopes across 6 categories:
CategoryScopesDescription
dataread, write, delete, *Data resource access
modeltrain, evaluate, deploy, attest, *ML model lifecycle
toolsearch.web, search.db, execute, *Tool invocation
agentdelegate, manage, inspect, *Agent lifecycle management
adminconfig, audit, billing, *Administrative operations
receiptcreate, verify, revoke, *Receipt management

​
Scope Format Reference

resource:action         Standard scope (e.g., "data:read")
resource:*              Wildcard scope (e.g., "data:*" grants all data actions)
!resource:action        Negation scope (e.g., "!data:delete" explicitly denies)
resource:sub.action     Dotted sub-actions (e.g., "tool:search.web")

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Query Parameters

​
category
enum<string>

Filter scopes by category

Available options:
data,
model,
tool,
agent,
admin,
receipt,
custom

Response

Available scopes

​
id
string<uuid>
​
tenant_id
string<uuid> | null
​
scope
string
​
resource
string
​
action
string
​
display_name
string
​
description
string
​
category
string
​
is_builtin
boolean
​
created_at
string<date-time>