curl --request POST \
--url https://api.example.com/keys \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "<string>",
"source": "<string>",
"is_platform": true,
"type_permissions": {},
"extension_permissions": {},
"edge_permissions": {},
"metadata_permissions": {}
}
'import requests
url = "https://api.example.com/keys"
payload = {
"label": "<string>",
"source": "<string>",
"is_platform": True,
"type_permissions": {},
"extension_permissions": {},
"edge_permissions": {},
"metadata_permissions": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label: '<string>',
source: '<string>',
is_platform: true,
type_permissions: {},
extension_permissions: {},
edge_permissions: {},
metadata_permissions: {}
})
};
fetch('https://api.example.com/keys', 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.example.com/keys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'label' => '<string>',
'source' => '<string>',
'is_platform' => true,
'type_permissions' => [
],
'extension_permissions' => [
],
'edge_permissions' => [
],
'metadata_permissions' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/keys"
payload := strings.NewReader("{\n \"label\": \"<string>\",\n \"source\": \"<string>\",\n \"is_platform\": true,\n \"type_permissions\": {},\n \"extension_permissions\": {},\n \"edge_permissions\": {},\n \"metadata_permissions\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/keys")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"<string>\",\n \"source\": \"<string>\",\n \"is_platform\": true,\n \"type_permissions\": {},\n \"extension_permissions\": {},\n \"edge_permissions\": {},\n \"metadata_permissions\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/keys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"<string>\",\n \"source\": \"<string>\",\n \"is_platform\": true,\n \"type_permissions\": {},\n \"extension_permissions\": {},\n \"edge_permissions\": {},\n \"metadata_permissions\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"key": "<string>",
"label": "<string>",
"source": "<string>",
"role": "admin",
"default_tier": "library",
"is_platform": true,
"type_permissions": {},
"created_at": "<string>",
"last_used_at": "<string>",
"extension_permissions": {},
"edge_permissions": {},
"metadata_permissions": {}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"details": {}
}
}Create an API key
Creates a new API key in the caller’s tenant. The plaintext key field is returned once in the response — the server never shows it again. Store it securely; rotating means revoking the old key and creating a new one.
role controls scope: admin bypasses every permission check; tenant_admin is the admin tier within a tenant; member is scoped by the three permission maps (type_permissions, extension_permissions, edge_permissions) plus metadata_permissions. source is stamped onto every item written by the key and is unique per tenant. default_tier stamps library or feed when the writing client omits a tier.
In bootstrap mode (zero keys exist on a fresh server), no auth is required and the minted key is always admin. Once any key exists, bootstrap mode disables — further key creation requires an admin or tenant_admin token. See Permissions for the permission-map grammar.
curl --request POST \
--url https://api.example.com/keys \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "<string>",
"source": "<string>",
"is_platform": true,
"type_permissions": {},
"extension_permissions": {},
"edge_permissions": {},
"metadata_permissions": {}
}
'import requests
url = "https://api.example.com/keys"
payload = {
"label": "<string>",
"source": "<string>",
"is_platform": True,
"type_permissions": {},
"extension_permissions": {},
"edge_permissions": {},
"metadata_permissions": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label: '<string>',
source: '<string>',
is_platform: true,
type_permissions: {},
extension_permissions: {},
edge_permissions: {},
metadata_permissions: {}
})
};
fetch('https://api.example.com/keys', 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.example.com/keys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'label' => '<string>',
'source' => '<string>',
'is_platform' => true,
'type_permissions' => [
],
'extension_permissions' => [
],
'edge_permissions' => [
],
'metadata_permissions' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/keys"
payload := strings.NewReader("{\n \"label\": \"<string>\",\n \"source\": \"<string>\",\n \"is_platform\": true,\n \"type_permissions\": {},\n \"extension_permissions\": {},\n \"edge_permissions\": {},\n \"metadata_permissions\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/keys")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"<string>\",\n \"source\": \"<string>\",\n \"is_platform\": true,\n \"type_permissions\": {},\n \"extension_permissions\": {},\n \"edge_permissions\": {},\n \"metadata_permissions\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/keys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"<string>\",\n \"source\": \"<string>\",\n \"is_platform\": true,\n \"type_permissions\": {},\n \"extension_permissions\": {},\n \"edge_permissions\": {},\n \"metadata_permissions\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"key": "<string>",
"label": "<string>",
"source": "<string>",
"role": "admin",
"default_tier": "library",
"is_platform": true,
"type_permissions": {},
"created_at": "<string>",
"last_used_at": "<string>",
"extension_permissions": {},
"edge_permissions": {},
"metadata_permissions": {}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"details": {}
}
}Authorizations
Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)
Body
11 - 200admin, tenant_admin, member library, feed Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
API key created
admin, tenant_admin, member library, feed Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes