Create token

Last updated Jun 14, 2026

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tierintegerRequired

One of1234

scopesarray<object>Optional

principalobjectRequired

human_idstringRequired

agent_idstringOptional

portfolio_idstringOptional

Bind the new token to one portfolio. The token becomes portfolio-scoped — only an unscoped key may set this.

limitsobjectOptional

api_versionstring<date>Required

Format date

acknowledgementsarray<object>Required

Per-token acknowledgements affirmed at creation. Required slugs depend on the token's tier and scopes[].allow:

not_legal_advice — always required
agent_action_binds_principal — required when tier >= 3
tier_4_standing_authority_acknowledged — required when tier == 4
incorporator_signature_authorized — required when scopes[].allow contains entities.submit Each entry binds to a specific natural-person stakeholder. See acknowledgements and legal basis.

slugstringRequired

Typed identifier for a class of risk the customer is affirming awareness of. Each slug has canonical plain-English text and a version, fetched via GET /v1/acknowledgements. Acknowledgements are bound to natural-person stakeholders and expire 90 days after acceptance; ToS-version supersession invalidates open acknowledgements under the prior version. See acknowledgements.

One of"not_legal_advice""not_tax_advice""agent_action_binds_principal""tier_4_standing_authority_acknowledged""incorporator_signature_authorized""formation_is_legally_binding""formation_creates_tax_obligations""83b_election_strict_30_day_deadline""equity_grant_is_securities_issuance""dissolution_is_irreversible""service_of_process_must_reach_human""late_filing_penalty_accepted"

versionstringRequired

Version of the canonical text the stakeholder affirmed. Mismatch → invalidates the acknowledgement.

accepted_by_stakeholder_idstringRequired

The natural-person stakeholder who affirmed this acknowledgement.

accepted_atintegerRequired

Unix timestamp (seconds since epoch) when the stakeholder typed/clicked the acknowledgement affordance.

ipstringOptional

IP address of the affirming human at acceptance time. Captured for audit.

user_agentstringOptional

User agent of the affirming human at acceptance time. Captured for audit.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/tokens" \  -H "Content-Type: application/json" \  -d '{    "tier": 0,    "scopes": [      {}    ],    "principal": {      "human_id": "usr_4Kj2m8pQ",      "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"  }'

const body = JSON.stringify({  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"})fetch("https://api.mattermode.com/v1/tokens", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/tokens"  body := strings.NewReader(`{    "tier": 0,    "scopes": [      {}    ],    "principal": {      "human_id": "usr_4Kj2m8pQ",      "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "tier": 0,    "scopes": [        {}    ],    "principal": {        "human_id": "usr_4Kj2m8pQ",        "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"}resp = requests.post(    "https://api.mattermode.com/v1/tokens",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/tokens"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/tokens", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/tokens' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"}'

const response = await fetch("https://api.mattermode.com/v1/tokens", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "tier": 0,    "scopes": [      {}    ],    "principal": {      "human_id": "usr_4Kj2m8pQ",      "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "id": "tok_4Kj2m8pQ",
  "object": "token",
  "tier": 0,
  "scopes": [
    {}
  ],
  "principal": {
    "human_id": "usr_4Kj2m8pQ"
  },
  "limits": {},
  "api_version": "2026-05-01",
  "revoked_at": 0,
  "last_used_at": 0,
  "metadata": {},
  "created": 1745539200,
  "updated": 1745539200,
  "livemode": false
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
  "doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30
}

Create a token.

Mint a scoped agent token (tok_…) representing a delegation of authority from a human principal to an autonomous or semi-autonomous worker. Tokens are the unit of access control for AI-agent integrations, internal automation, embedded customer flows, and white-label deployments — pass portfolio_id to mint a portfolio-scoped key confined to one end customer's portfolio.

Tier model (tier) - tier_1 — observe. Read-only. Suitable for analytics agents, dashboards, and "show me the cap table" use cases. Cannot mutate state. - tier_2 — prepare. May resolve Intents and stage drafts, but cannot execute. The classic "let an agent fill in the form for me" tier. - tier_3 — execute. May commit non-destructive mutations and trigger filings. Destructive operations (dissolve, void, revoke) and any cascade involving > $10k in fees still require a paired human Authorization. - tier_4 — autonomous. Full execution, including most destructive paths. Service-of-process mail, dissolution, and material cap-table changes still escalate to a human Authorization. Reserved for long-running studios and operators with established history.

scopes further narrow the access (equity.read, filings.write, etc.); principal names the human who is delegating; limits caps spend per period; api_version pins the token to a dated API version so a model upgrade doesn't break the agent's contract.

Returns 200 OK with the token resource. The plaintext value is returned exactly once in secret and must be persisted by the caller — Matter only stores the hash. Idempotent via Idempotency-Key. See idempotency.

Last updated Jun 14, 2026

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tierintegerRequired

One of1234

scopesarray<object>Optional

principalobjectRequired

human_idstringRequired

agent_idstringOptional

portfolio_idstringOptional

Bind the new token to one portfolio. The token becomes portfolio-scoped — only an unscoped key may set this.

limitsobjectOptional

api_versionstring<date>Required

Format date

acknowledgementsarray<object>Required

Per-token acknowledgements affirmed at creation. Required slugs depend on the token's tier and scopes[].allow:

not_legal_advice — always required
agent_action_binds_principal — required when tier >= 3
tier_4_standing_authority_acknowledged — required when tier == 4
incorporator_signature_authorized — required when scopes[].allow contains entities.submit Each entry binds to a specific natural-person stakeholder. See acknowledgements and legal basis.

slugstringRequired

versionstringRequired

Version of the canonical text the stakeholder affirmed. Mismatch → invalidates the acknowledgement.

accepted_by_stakeholder_idstringRequired

The natural-person stakeholder who affirmed this acknowledgement.

accepted_atintegerRequired

Unix timestamp (seconds since epoch) when the stakeholder typed/clicked the acknowledgement affordance.

ipstringOptional

IP address of the affirming human at acceptance time. Captured for audit.

user_agentstringOptional

User agent of the affirming human at acceptance time. Captured for audit.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/tokens" \  -H "Content-Type: application/json" \  -d '{    "tier": 0,    "scopes": [      {}    ],    "principal": {      "human_id": "usr_4Kj2m8pQ",      "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"  }'

const body = JSON.stringify({  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"})fetch("https://api.mattermode.com/v1/tokens", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/tokens"  body := strings.NewReader(`{    "tier": 0,    "scopes": [      {}    ],    "principal": {      "human_id": "usr_4Kj2m8pQ",      "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "tier": 0,    "scopes": [        {}    ],    "principal": {        "human_id": "usr_4Kj2m8pQ",        "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"}resp = requests.post(    "https://api.mattermode.com/v1/tokens",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/tokens"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/tokens", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/tokens' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "tier": 0,  "scopes": [    {}  ],  "principal": {    "human_id": "usr_4Kj2m8pQ",    "agent_id": "agt_paralegal_v2"  },  "limits": {},  "api_version": "2026-04-25"}'

const response = await fetch("https://api.mattermode.com/v1/tokens", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "tier": 0,    "scopes": [      {}    ],    "principal": {      "human_id": "usr_4Kj2m8pQ",      "agent_id": "agt_paralegal_v2"    },    "limits": {},    "api_version": "2026-04-25"  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "id": "tok_4Kj2m8pQ",
  "object": "token",
  "tier": 0,
  "scopes": [
    {}
  ],
  "principal": {
    "human_id": "usr_4Kj2m8pQ"
  },
  "limits": {},
  "api_version": "2026-05-01",
  "revoked_at": 0,
  "last_used_at": 0,
  "metadata": {},
  "created": 1745539200,
  "updated": 1745539200,
  "livemode": false
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
  "doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30
}

Create a token.

Request Body

Response Body

201application/json

400application/problem+json

401application/problem+json

429application/problem+json

Create a token.

Request Body

Response Body

201application/json

400application/problem+json

401application/problem+json

429application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`