Me

Package: agentrouter.identity.v1 Service: MeService

Endpoints

Initiate OIDC login

What it does: Initiates an OIDC authorization-code + PKCE flow. Returns an authorization_url the caller must redirect the user's browser to. After the IdP authenticates and redirects to redirect_uri, the platform establishes a session cookie for subsequent requests.

Request fields:

FieldRequiredDescription
issuernoOperator's OIDC issuer alias (allows multi-IdP operators to select). Empty selects the default issuer for the operator domain.
redirect_uriyesWhere the IdP should redirect after authentication. For the CLI this is a localhost loopback URL bound to a free port.
code_challengeyesPKCE code challenge generated by the client.
code_challenge_methodyesPKCE code-challenge method. Only S256 is accepted.

Response fields:

FieldRequiredDescription
authorization_urloutput-onlyURL the client follows to the upstream IdP.
stateoutput-onlyOpaque state value bound to the request. Echoed by the IdP and verified by the /v1/auth/callback handler.
 
{"signatures":{"go":"func (x *MeClient) Login(ctx context.Context, req *identityv1.LoginRequest) (*identityv1.LoginResponse, error)","python":"login(req: identity_service_pb2.LoginRequest) -\u003e LoginResponse","typescript":"login(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.LoginRequestSchema\u003e): Promise\u003cLoginResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/login\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"issuer\": \"...\",\n    \"redirect_uri\": \"...\",\n    \"code_challenge\": \"...\",\n    \"code_challenge_method\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.LoginRequest{}\n\n\tresp, err := client.Me().Login(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/login\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.LoginRequest()\ntry:\n    result = client.me.login(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.login(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/login\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"issuer\": \"...\",\n    \"redirect_uri\": \"...\",\n    \"code_challenge\": \"...\",\n    \"code_challenge_method\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/login","slug":"initiate-oidc-login"}

Log out

What it does: Invalidates the caller's current OIDC session. Subsequent requests using the session cookie return 401 unauthenticated. Does not revoke API keys the identity may have issued.

Request body: None.

{"signatures":{"go":"func (x *MeClient) Logout(ctx context.Context, req *identityv1.LogoutRequest) (*identityv1.LogoutResponse, error)","python":"logout(req: identity_service_pb2.LogoutRequest) -\u003e LogoutResponse","typescript":"logout(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.LogoutRequestSchema\u003e): Promise\u003cLogoutResponse\u003e","cli":"tare api logout","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/logout\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithSessionToken(os.Getenv(\"AGENTROUTER_SESSION_TOKEN\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.LogoutRequest{}\n\n\tresp, err := client.Me().Logout(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/logout\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    session_token=os.environ[\"AGENTROUTER_SESSION_TOKEN\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.LogoutRequest()\ntry:\n    result = client.me.logout(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  sessionToken: process.env.AGENTROUTER_SESSION_TOKEN,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.logout(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api logout","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/logout\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},"persona":"Dashboard user (session token)","httpVerb":"POST","httpPath":"/v1/auth/logout","slug":"log-out"}

Sign in with a password

Changed in v0.5.0 (new features): The management plane now serves password sign-in, reset, and change directly, using the same password format as the auth service. The surface stays off until ENABLE_PASSWORD_AUTH is true with corporate login off; reset mail also needs SMTP_HOST, and without it no reset links are issued.

What it does: Exchanges an email and password for a session. Serves the same credential store as the auth service (authn.account, provider "credential"), so a password set by either stack works on both. Registered only where credential sign-in is enabled: a deployment running corporate SSO has no password surface at all.

Request fields:

FieldRequiredDescription
emailyesundocumented
passwordyesundocumented

Response fields:

FieldRequiredDescription
session_tokenoutput-onlySession token for the new session, returned exactly once. The HTTP bridge turns it into the same signed cookie the OIDC callback sets.
identityoutput-onlyThe identity that signed in.
 
{"signatures":{"go":"func (x *MeClient) SignInWithPassword(ctx context.Context, req *identityv1.SignInWithPasswordRequest) (*identityv1.SignInWithPasswordResponse, error)","python":"sign_in_with_password(req: identity_service_pb2.SignInWithPasswordRequest) -\u003e SignInWithPasswordResponse","typescript":"signInWithPassword(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.SignInWithPasswordRequestSchema\u003e): Promise\u003cSignInWithPasswordResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/sign-in/email\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"password\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.SignInWithPasswordRequest{}\n\n\tresp, err := client.Me().SignInWithPassword(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/signinwithpassword\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.SignInWithPasswordRequest()\ntry:\n    result = client.me.sign_in_with_password(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.signInWithPassword(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/sign-in/email\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"password\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/sign-in/email","slug":"sign-in-with-a-password"}

Request a password reset

Changed in v0.5.0 (new features): The management plane now serves password sign-in, reset, and change directly, using the same password format as the auth service. The surface stays off until ENABLE_PASSWORD_AUTH is true with corporate login off; reset mail also needs SMTP_HOST, and without it no reset links are issued.

What it does: Emails a single-use reset link. The response is the same whether or not the address has an account, so it cannot be used to discover who has one.

Request fields:

FieldRequiredDescription
emailyesundocumented
redirect_tonoWhere the emailed link should land. Must be an allowed redirect target.
 
{"signatures":{"go":"func (x *MeClient) RequestPasswordReset(ctx context.Context, req *identityv1.RequestPasswordResetRequest) (*identityv1.RequestPasswordResetResponse, error)","python":"request_password_reset(req: identity_service_pb2.RequestPasswordResetRequest) -\u003e RequestPasswordResetResponse","typescript":"requestPasswordReset(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.RequestPasswordResetRequestSchema\u003e): Promise\u003cRequestPasswordResetResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/request-password-reset\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"redirect_to\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.RequestPasswordResetRequest{}\n\n\tresp, err := client.Me().RequestPasswordReset(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/requestpasswordreset\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.RequestPasswordResetRequest()\ntry:\n    result = client.me.request_password_reset(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.requestPasswordReset(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/request-password-reset\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"redirect_to\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/request-password-reset","slug":"request-a-password-reset"}

Reset a password

Changed in v0.5.0 (new features): The management plane now serves password sign-in, reset, and change directly, using the same password format as the auth service. The surface stays off until ENABLE_PASSWORD_AUTH is true with corporate login off; reset mail also needs SMTP_HOST, and without it no reset links are issued.

What it does: Consumes a reset token and sets the new password. The token is single-use and expires an hour after it is issued.

Request fields:

FieldRequiredDescription
tokenyesundocumented
new_passwordyesundocumented
 
{"signatures":{"go":"func (x *MeClient) ResetPassword(ctx context.Context, req *identityv1.ResetPasswordRequest) (*identityv1.ResetPasswordResponse, error)","python":"reset_password(req: identity_service_pb2.ResetPasswordRequest) -\u003e ResetPasswordResponse","typescript":"resetPassword(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ResetPasswordRequestSchema\u003e): Promise\u003cResetPasswordResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/reset-password\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"token\": \"...\",\n    \"new_password\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ResetPasswordRequest{}\n\n\tresp, err := client.Me().ResetPassword(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/resetpassword\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ResetPasswordRequest()\ntry:\n    result = client.me.reset_password(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.resetPassword(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/reset-password\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"token\": \"...\",\n    \"new_password\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/reset-password","slug":"reset-a-password"}

Change your password

Changed in v0.5.0 (new features): The management plane now serves password sign-in, reset, and change directly, using the same password format as the auth service. The surface stays off until ENABLE_PASSWORD_AUTH is true with corporate login off; reset mail also needs SMTP_HOST, and without it no reset links are issued.

What it does: Sets a new password for the signed-in caller, who must prove the current one. Every OTHER session the user holds is revoked, so a password change ends any session an attacker may already have.

Request fields:

FieldRequiredDescription
current_passwordyesundocumented
new_passwordyesundocumented
 
{"signatures":{"go":"func (x *MeClient) ChangePassword(ctx context.Context, req *identityv1.ChangePasswordRequest) (*identityv1.ChangePasswordResponse, error)","python":"change_password(req: identity_service_pb2.ChangePasswordRequest) -\u003e ChangePasswordResponse","typescript":"changePassword(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ChangePasswordRequestSchema\u003e): Promise\u003cChangePasswordResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/change-password\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"current_password\": \"...\",\n    \"new_password\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithSessionToken(os.Getenv(\"AGENTROUTER_SESSION_TOKEN\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ChangePasswordRequest{}\n\n\tresp, err := client.Me().ChangePassword(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/changepassword\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    session_token=os.environ[\"AGENTROUTER_SESSION_TOKEN\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ChangePasswordRequest()\ntry:\n    result = client.me.change_password(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  sessionToken: process.env.AGENTROUTER_SESSION_TOKEN,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.changePassword(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/change-password\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"current_password\": \"...\",\n    \"new_password\": \"...\"\n  }'"},"persona":"Dashboard user (session token)","httpVerb":"POST","httpPath":"/v1/auth/change-password","slug":"change-your-password"}

Sign up with a password

Changed in v0.5.0 (new features): Self-serve sign-up now works against the management plane: confirm the emailed link once to verify and sign in (a second open does not mint another session). Where a challenge is configured, sign-up and sign-in ask for it; an unreachable challenge service blocks sign-up but lets sign-in continue. Needs ENABLE_PASSWORD_AUTH with corporate login off, and SMTP_HOST; sign-up itself stays off unless turned on.

What it does: Creates an account with an email and password and sends a verification link. Available only where self-serve sign-up is enabled; elsewhere an administrator provisions the user instead.

Request fields:

FieldRequiredDescription
emailyesundocumented
passwordyesundocumented
namenoDisplay name. Defaults to the email local-part when empty.
callback_urlnoWhere the verification link should return the user.

Response fields:

FieldRequiredDescription
identity_idoutput-onlyThe created identity. No session is issued: the address must be verified first, which is what the emailed link does.
emailoutput-onlyundocumented
 
{"signatures":{"go":"func (x *MeClient) SignUpWithPassword(ctx context.Context, req *identityv1.SignUpWithPasswordRequest) (*identityv1.SignUpWithPasswordResponse, error)","python":"sign_up_with_password(req: identity_service_pb2.SignUpWithPasswordRequest) -\u003e SignUpWithPasswordResponse","typescript":"signUpWithPassword(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.SignUpWithPasswordRequestSchema\u003e): Promise\u003cSignUpWithPasswordResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/sign-up/email\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"password\": \"...\",\n    \"name\": \"...\",\n    \"callback_url\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.SignUpWithPasswordRequest{}\n\n\tresp, err := client.Me().SignUpWithPassword(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/signupwithpassword\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.SignUpWithPasswordRequest()\ntry:\n    result = client.me.sign_up_with_password(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.signUpWithPassword(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/sign-up/email\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"password\": \"...\",\n    \"name\": \"...\",\n    \"callback_url\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/sign-up/email","slug":"sign-up-with-a-password"}

Send a verification email

Changed in v0.5.0 (new features): Self-serve sign-up now works against the management plane: confirm the emailed link once to verify and sign in (a second open does not mint another session). Where a challenge is configured, sign-up and sign-in ask for it; an unreachable challenge service blocks sign-up but lets sign-in continue. Needs ENABLE_PASSWORD_AUTH with corporate login off, and SMTP_HOST; sign-up itself stays off unless turned on.

What it does: Re-sends the verification link. The response is the same whether or not the address has an unverified account.

Request fields:

FieldRequiredDescription
emailyesundocumented
callback_urlnoundocumented
 
{"signatures":{"go":"func (x *MeClient) SendVerificationEmail(ctx context.Context, req *identityv1.SendVerificationEmailRequest) (*identityv1.SendVerificationEmailResponse, error)","python":"send_verification_email(req: identity_service_pb2.SendVerificationEmailRequest) -\u003e SendVerificationEmailResponse","typescript":"sendVerificationEmail(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.SendVerificationEmailRequestSchema\u003e): Promise\u003cSendVerificationEmailResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/send-verification-email\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"callback_url\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.SendVerificationEmailRequest{}\n\n\tresp, err := client.Me().SendVerificationEmail(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/sendverificationemail\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.SendVerificationEmailRequest()\ntry:\n    result = client.me.send_verification_email(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.sendVerificationEmail(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/send-verification-email\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"callback_url\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/send-verification-email","slug":"send-a-verification-email"}

Verify an email address

Changed in v0.5.0 (new features): Self-serve sign-up now works against the management plane: confirm the emailed link once to verify and sign in (a second open does not mint another session). Where a challenge is configured, sign-up and sign-in ask for it; an unreachable challenge service blocks sign-up but lets sign-in continue. Needs ENABLE_PASSWORD_AUTH with corporate login off, and SMTP_HOST; sign-up itself stays off unless turned on.

What it does: Consumes a verification link and marks the address verified. The token is the same signed form the auth service issues, so a link from either stack works on both.

Request fields:

FieldRequiredDescription
tokenyesundocumented

Response fields:

FieldRequiredDescription
identity_idoutput-onlyundocumented
session_tokenoutput-onlySession token for the signed-in user, returned exactly once: verifying is proof of control of the address, so it signs the user in the way the auth service does.
 
{"signatures":{"go":"func (x *MeClient) VerifyEmail(ctx context.Context, req *identityv1.VerifyEmailRequest) (*identityv1.VerifyEmailResponse, error)","python":"verify_email(req: identity_service_pb2.VerifyEmailRequest) -\u003e VerifyEmailResponse","typescript":"verifyEmail(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.VerifyEmailRequestSchema\u003e): Promise\u003cVerifyEmailResponse\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/auth/verify-email\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.VerifyEmailRequest{}\n\n\tresp, err := client.Me().VerifyEmail(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/verifyemail\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.VerifyEmailRequest()\ntry:\n    result = client.me.verify_email(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.verifyEmail(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl \"${AGENTROUTER_BASE_URL}/v1/auth/verify-email\""},"persona":"Public (no credential required)","httpVerb":"GET","httpPath":"/v1/auth/verify-email","slug":"verify-an-email-address"}

Get current identity

Changed in v0.5.0 (new features): GetMe now returns session claims to a signed-in browser session: the caller's organization-level permission set and whether the deployment has an administrator. A console reading its session from the management plane gets the same permission view the auth service provides today, including the difference between "no access" and "could not tell". Callers using an API key see no change.

What it does: Returns the full identity record for the authenticated caller. Use to verify which identity a credential belongs to, populate a "logged in as" UI element, or confirm role assignments before making permission-gated calls. A session caller also receives its session claims: the organization-level permission set and whether the deployment has an administrator.

Request body: None.

Response fields:

FieldRequiredDescription
identitynoFull identity record for the authenticated caller.
session_claimsoutput-onlyClaims a browser session reads to render its permission view. Set only for a session caller on a deployment that resolves permissions; absent for an API key.
 
{"signatures":{"go":"func (x *MeClient) GetMe(ctx context.Context, req *identityv1.GetMeRequest) (*identityv1.GetMeResponse, error)","python":"get_me(req: identity_service_pb2.GetMeRequest) -\u003e GetMeResponse","typescript":"getMe(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.GetMeRequestSchema\u003e): Promise\u003cGetMeResponse\u003e","cli":"tare api whoami","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.GetMeRequest{}\n\n\tresp, err := client.Me().GetMe(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/getme\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.GetMeRequest()\ntry:\n    result = client.me.get_me(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.getMe(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api whoami","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/me","slug":"get-current-identity"}

Update your profile

Changed in v0.5.0 (new features): Signed-in users can change their own display name through the management plane API. Only the name can be changed this way, and the call needs a browser or CLI sign-in rather than an API key.

What it does: Changes the signed-in caller's own display name (authn.user.name) and returns the updated identity. It acts only on the caller: there is no user id in the request, so it cannot rename anyone else. Name only. fraser-auth's better-auth update-user also accepts image, phone, website and address, but the console's profile dialog sends only name, so that is all this serves. Email and role are never caller-editable. Session-only, like ChangePassword: an API key is refused even though it belongs to the same user.

Request fields:

FieldRequiredDescription
namenoThe new display name. Leading and trailing whitespace is trimmed, and a name that is empty after trimming is refused.

Response fields:

FieldRequiredDescription
identitynoThe caller's identity record after the update.
 
{"signatures":{"go":"func (x *MeClient) UpdateMe(ctx context.Context, req *identityv1.UpdateMeRequest) (*identityv1.UpdateMeResponse, error)","python":"update_me(req: identity_service_pb2.UpdateMeRequest) -\u003e UpdateMeResponse","typescript":"updateMe(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.UpdateMeRequestSchema\u003e): Promise\u003cUpdateMeResponse\u003e","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/me\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithSessionToken(os.Getenv(\"AGENTROUTER_SESSION_TOKEN\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.UpdateMeRequest{}\n\n\tresp, err := client.Me().UpdateMe(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/updateme\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    session_token=os.environ[\"AGENTROUTER_SESSION_TOKEN\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.UpdateMeRequest()\ntry:\n    result = client.me.update_me(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  sessionToken: process.env.AGENTROUTER_SESSION_TOKEN,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.updateMe(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/me\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"...\"\n  }'"},"persona":"Dashboard user (session token)","httpVerb":"PATCH","httpPath":"/v1/me","slug":"update-your-profile"}

Issue an API key

Changed in v0.1.5 (new features): Management keys can now receive built-in platform roles by explicit delegation when a key is issued or updated. The issuer's platform permissions bound what can be delegated. Legacy platform scopes are converted to explicit role bindings on upgrade, and bindings written by the retired scope inference are removed.

Changed in v0.1.5 (new features): A management API key's scopes are now readable: the key object returned when a key is issued, listed, or re-scoped carries its scope set, so an assignment can be confirmed directly instead of inferred from a refused call. An empty list means the key carries no explicit scopes and resolves through its owner's roles, not that it has none.

Changed in v0.1.5 (bug fixes): Creating a management API key now follows the api_keys.create permission rather than the name of the role that carries it. A User Admin, a custom role, or a direct grant holding that permission was refused, so granting the permission the denial named could not work and only a Super Admin could create these keys. The console's key-type chooser follows the same permission, so the option appears for everyone who can use it. The key such a person creates carries their own access, not full administrative access. Only someone who can already administer the organization can put that on a key.

What it does: Issues a new long-lived API key for the caller. The secret field in the response is returned exactly once and cannot be retrieved again. Store it in a secrets manager immediately. Issuing a management key (type API_KEY_TYPE_MANAGEMENT) requires the api_keys.create permission for the target customer -- the built-in Super Admin and User Admin roles carry it -- or the request fails with PERMISSION_DENIED. Inference keys (the default) are open to any authenticated session. The key carries the caller's own access, not the organization's: a caller who cannot already administer the customer receives read-only management scopes, and asking for broader ones fails with PERMISSION_DENIED.

Request fields:

FieldRequiredDescription
nameyesHuman-friendly label for the key. Surfaced in ia keys list output.
typenoWhat the key is authorized to do. Unspecified defaults to PROMPT.
project_idnoProject the key is scoped to. Management keys must set this explicitly: "default" creates an organization key; any other value creates a project key. Inference keys retain the legacy optional behavior.
scopesnoOptional least-privilege scopes for a management key, drawn from the server's assignable scope catalog. Empty snapshots the caller's current assignable scope tokens. The server rejects any scope outside the catalog or that the caller is not authorized to delegate.
customer_idnoCustomer the management key belongs to. Required for management keys so project identifiers are never resolved against an arbitrary membership. Inference keys retain the legacy optional behavior.
tagsnoOptional (tag_key, tag_value) pairs to attach to the newly issued key (tars.policy.v1 api_key_tags; fraser#5442). Each tag_key/tag_value pair must already be registered in the caller's tag_schema catalog. A tag_key that is internal:-prefixed is REJECTED with InvalidArgument -- that namespace is reserved for trusted, system-only writers (e.g. the goose promo flow) and is never settable through this user-facing RPC. Field 6, not 5: main released customer_id on 5 while this branch was open. Renumbering the UNRELEASED field (this one) is the wire-safe side of that collision.
platform_rolesnoOptional built-in platform roles to delegate to this management key. The server rejects unknown, custom, and over-privileged roles. Omission creates a key with no platform role.
idempotency_keynoOptional caller-supplied idempotency key.

Response fields:

FieldRequiredDescription
keynoMetadata for the newly issued key (id, name, prefix, type, state).
secretoutput-onlyPlaintext API key value. Returned exactly once at issue time.
effective_capabilitiesoutput-onlyEffective RBAC capability of the issued key. Message presence is significant: absent means that the server did not resolve capabilities; present with empty lists means that it resolved no permission grants.
 
{"signatures":{"go":"func (x *MeClient) IssueMyKey(ctx context.Context, req *identityv1.IssueMyKeyRequest) (*identityv1.IssueMyKeyResponse, error)","python":"issue_my_key(req: identity_service_pb2.IssueMyKeyRequest) -\u003e IssueMyKeyResponse","typescript":"issueMyKey(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.IssueMyKeyRequestSchema\u003e): Promise\u003cIssueMyKeyResponse\u003e","cli":"tare api keys create --name $NAME --type API_KEY_TYPE_MANAGEMENT --customer-id $CUSTOMER_ID --project-id $PROJECT_ID","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/me/keys\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"...\",\n    \"type\": \"API_KEY_TYPE_MANAGEMENT\",\n    \"project_id\": \"...\",\n    \"scopes\": [],\n    \"customer_id\": \"...\",\n    \"tags\": {},\n    \"platform_roles\": [],\n    \"idempotency_key\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Management key; omitted type defaults to inference (PROMPT).\n\treq := \u0026identityv1.IssueMyKeyRequest{\n\t\tName:       \"...\",\n\t\tType:       identityv1.ApiKeyType_API_KEY_TYPE_MANAGEMENT,\n\t\tCustomerId: \"...\",\n\t\tProjectId:  \"...\",\n\t}\n\n\tresp, err := client.Me().IssueMyKey(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/issuemykey\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom agentrouter_sdk import Client, API_KEY_TYPE_MANAGEMENT\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Replace the placeholder values below.\nname = \"...\"\ncustomer_id = \"...\"\nproject_id = \"...\"\ntry:\n    result = client.me.issue_key(name, key_type=API_KEY_TYPE_MANAGEMENT, customer_id=customer_id, project_id=project_id)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client, ApiKeyType } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Replace the placeholder values below.\nconst name = \"...\"\nconst customerId = \"...\"\nconst projectId = \"...\"\ntry {\n  const result = await client.me.issueKey(name, { type: ApiKeyType.MANAGEMENT, customerId, projectId })\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api keys create --name $NAME --type API_KEY_TYPE_MANAGEMENT --customer-id $CUSTOMER_ID --project-id $PROJECT_ID","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/me/keys\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"...\",\n    \"type\": \"API_KEY_TYPE_MANAGEMENT\",\n    \"project_id\": \"...\",\n    \"scopes\": [],\n    \"customer_id\": \"...\",\n    \"tags\": {},\n    \"platform_roles\": [],\n    \"idempotency_key\": \"...\"\n  }'"},"persona":"Authenticated (API key or session token)","httpVerb":"POST","httpPath":"/v1/me/keys","slug":"issue-an-api-key"}

List API keys

Changed in v0.1.5 (new features): A management API key's scopes are now readable: the key object returned when a key is issued, listed, or re-scoped carries its scope set, so an assignment can be confirmed directly instead of inferred from a refused call. An empty list means the key carries no explicit scopes and resolves through its owner's roles, not that it has none.

What it does: Lists all API keys belonging to the caller. Returns metadata (id, name, creation timestamp, last-used timestamp) but never the plaintext secret.

Request fields:

FieldRequiredDescription
pagenoPagination cursor and page size for the listing.

Response fields:

FieldRequiredDescription
keysnoThe caller's API keys (metadata only; never the plaintext secret).
pagenoPagination state; carries the next-page cursor when more remain.
 
{"signatures":{"go":"func (x *MeClient) ListMyKeys(ctx context.Context, req *identityv1.ListMyKeysRequest) (*identityv1.ListMyKeysResponse, error)","python":"list_my_keys(req: identity_service_pb2.ListMyKeysRequest) -\u003e ListMyKeysResponse","typescript":"listMyKeys(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ListMyKeysRequestSchema\u003e): Promise\u003cListMyKeysResponse\u003e","cli":"tare api keys list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/keys\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ListMyKeysRequest{}\n\n\tresp, err := client.Me().ListMyKeys(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/listmykeys\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ListMyKeysRequest()\ntry:\n    result = client.me.list_my_keys(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.listMyKeys(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api keys list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/keys\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/me/keys","slug":"list-api-keys"}

Revoke an API key

What it does: Permanently and irrevocably revokes an API key. Revocation propagates to all active data planes within sub-second; requests already in flight that passed authentication before propagation may still complete.

Request fields:

FieldRequiredDescription
key_idyesId (key_<ulid>) of the caller-owned key to revoke.
 
{"signatures":{"go":"func (x *MeClient) RevokeMyKey(ctx context.Context, req *identityv1.RevokeMyKeyRequest) (*identityv1.RevokeMyKeyResponse, error)","python":"revoke_my_key(req: identity_service_pb2.RevokeMyKeyRequest) -\u003e RevokeMyKeyResponse","typescript":"revokeMyKey(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.RevokeMyKeyRequestSchema\u003e): Promise\u003cRevokeMyKeyResponse\u003e","cli":"tare api keys revoke \u003ckey-id\u003e","curl":"curl -X DELETE \"${AGENTROUTER_BASE_URL}/v1/me/keys/key_01H...\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.RevokeMyKeyRequest{}\n\n\tresp, err := client.Me().RevokeMyKey(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/revokemykey\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.RevokeMyKeyRequest()\ntry:\n    result = client.me.revoke_my_key(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.revokeMyKey(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api keys revoke \u003ckey-id\u003e","curl":"curl -X DELETE \"${AGENTROUTER_BASE_URL}/v1/me/keys/key_01H...\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"DELETE","httpPath":"/v1/me/keys/{key_id}","slug":"revoke-an-api-key"}

Update an API key's scopes

Changed in v0.1.5 (new features): Management keys can now receive built-in platform roles by explicit delegation when a key is issued or updated. The issuer's platform permissions bound what can be delegated. Legacy platform scopes are converted to explicit role bindings on upgrade, and bindings written by the retired scope inference are removed.

Changed in v0.1.5 (new features): A management API key's scopes are now readable: the key object returned when a key is issued, listed, or re-scoped carries its scope set, so an assignment can be confirmed directly instead of inferred from a refused call. An empty list means the key carries no explicit scopes and resolves through its owner's roles, not that it has none.

What it does: Replaces the scope set of a caller-owned management key in place, so an existing key can be re-scoped without rotating its secret. The caller may only assign scopes it is authorized to delegate.

Request fields:

FieldRequiredDescription
key_idyesId of the caller-owned key whose scopes are being replaced.
scopesnoReplacement least-privilege scope set. The server rejects any scope the caller is not authorized to delegate. Proto3 repeated fields carry no field-presence bit, so an empty scopes is indistinguishable on the wire from an omitted one -- both leave the key's scopes UNTOUCHED (a caller updating only tags must not silently wipe an existing persisted grant). To replace it with the caller's current compatibility grant, set clear_scopes.
tagsnoReplacement (tag_key, tag_value) set (tars.policy.v1 api_key_tags; fraser#5442). By default (clear_tags = false), a non-empty tags map is MERGED into the key's existing tag set: named tags are added or overwritten, and any existing tag not named here is left untouched. Same catalog-validation / internal: rejection as IssueMyKeyRequest.tags. Proto3 maps carry no field-presence bit, so an empty tags map is indistinguishable on the wire from an omitted one -- both leave the key's tags UNTOUCHED (a caller updating only scopes must not silently wipe unrelated tags). To replace the tag set exactly (remove anything not named here), set clear_tags = true.
clear_tagsnoWhen true, removes every tag from the key first; tags (if any) are then re-added on top, so clear_tags: true + a non-empty tags is equivalent to a full replace. clear_tags: false (the default) with an empty tags leaves existing tags untouched -- see the tags comment.
clear_scopesnoWhen true, replaces the key's scopes with the caller's current read or admin compatibility grant. It never restores live owner-role projection. clear_scopes: false (the default) with an empty scopes leaves the key's current scopes untouched -- see the scopes comment. A non-empty scopes always replaces the override regardless of clear_scopes.
platform_rolesnoReplacement built-in platform roles for the key. A non-empty list replaces all current platform roles. An empty list leaves them unchanged unless clear_platform_roles is true.
clear_platform_rolesnoWhen true, removes all platform roles from the key. A non-empty platform_roles list is then applied as the replacement set.

Response fields:

FieldRequiredDescription
keynoThe updated key metadata (never the secret).
 
{"signatures":{"go":"func (x *MeClient) UpdateMyKey(ctx context.Context, req *identityv1.UpdateMyKeyRequest) (*identityv1.UpdateMyKeyResponse, error)","python":"update_my_key(req: identity_service_pb2.UpdateMyKeyRequest) -\u003e UpdateMyKeyResponse","typescript":"updateMyKey(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.UpdateMyKeyRequestSchema\u003e): Promise\u003cUpdateMyKeyResponse\u003e","cli":"tare api keys set-scopes \u003ckey-id\u003e","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/me/keys/key_01H...\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"scopes\": [],\n    \"tags\": {},\n    \"clear_tags\": false,\n    \"clear_scopes\": false,\n    \"platform_roles\": [],\n    \"clear_platform_roles\": false\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.UpdateMyKeyRequest{}\n\n\tresp, err := client.Me().UpdateMyKey(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/updatemykey\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.UpdateMyKeyRequest()\ntry:\n    result = client.me.update_my_key(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.updateMyKey(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api keys set-scopes \u003ckey-id\u003e","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/me/keys/key_01H...\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"scopes\": [],\n    \"tags\": {},\n    \"clear_tags\": false,\n    \"clear_scopes\": false,\n    \"platform_roles\": [],\n    \"clear_platform_roles\": false\n  }'"},"persona":"Authenticated (API key or session token)","httpVerb":"PATCH","httpPath":"/v1/me/keys/{key_id}","slug":"update-an-api-keys-scopes"}

List my projects

Changed in v0.1.5 (new features): A new endpoint, GET /v1/me/projects, lists the projects you can access and your role in each: a console or client can answer "which projects am I in" with the caller's own credential instead of an administrator key or a direct database read. Access covers project membership, project-scoped and organization-wide RBAC grants, plus your organization's default project.

What it does: Lists the projects the calling identity can access within one customer, with the caller's role in each. Access is the union of three sources: the caller's project_members rows, the projects their project-scoped RBAC bindings reach, and -- when they hold an org-scoped grant -- every project in the customer. The customer-wide default project travels with EVERY customer the caller belongs to, not only the oldest one that fills an omitted customer_id, and with a caller who has no customer yet, which is the first-login state it exists for. An established caller naming a tenant they hold no membership in does NOT receive that tenant's default project; they get an empty list. role reports what the platform actually enforces for the caller on that project, not merely what the membership row says, so a project listed as "admin" is one the caller is genuinely admitted to as owner. A caller with no access receives an empty page, not an error.

Request fields:

FieldRequiredDescription
customer_idnoCustomer scope to list within. Optional: empty resolves to the caller's default customer (their oldest project membership). Naming any other customer is permitted, but the listing is the constraint: an established caller with no membership and no binding there receives an empty list, not that customer's default project. One customer per call; this RPC never lists across customers.
pagenoPagination cursor and page size for the listing. Default page size is 100 and the server caps it at 1000; a larger request is silently reduced to the cap rather than rejected. common.v1.PageRequest defers both to the per-RPC docs, so they are stated here. order_by accepts "created_at" or "project_id", each optionally suffixed " asc" / " desc"; an omitted direction is ascending, while an empty order_by keeps the default "created_at desc". filter is not supported and is rejected rather than ignored.

Response fields:

FieldRequiredDescription
projectsnoProjects the caller can access, with their role in each.
pagenoPagination state; carries the next-page cursor when more remain.
 
{"signatures":{"go":"func (x *MeClient) ListMyProjects(ctx context.Context, req *identityv1.ListMyProjectsRequest) (*identityv1.ListMyProjectsResponse, error)","python":"list_my_projects(req: identity_service_pb2.ListMyProjectsRequest) -\u003e ListMyProjectsResponse","typescript":"listMyProjects(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ListMyProjectsRequestSchema\u003e): Promise\u003cListMyProjectsResponse\u003e","cli":"tare api projects mine","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/projects\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ListMyProjectsRequest{}\n\n\tresp, err := client.Me().ListMyProjects(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/listmyprojects\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ListMyProjectsRequest()\ntry:\n    result = client.me.list_my_projects(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.listMyProjects(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"cli":"tare api projects mine","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/projects\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/me/projects","slug":"list-my-projects"}

Resolve my permissions

Changed in v0.5.0 (new features): The management plane now serves the RBAC read surface directly: a caller can resolve their own permissions at an organization or project, list the project ids they can reach, and read the deployment's permission catalog. These answer from the same bindings the platform already enforces against, so what the API reports and what a request is allowed to do cannot drift apart. Nothing changes for existing callers yet -- the console continues to use the auth service until it is moved over.

What it does: Returns every RBAC permission the calling identity holds at one target: the customer's org level when project_id is empty, or that project otherwise. This is the read the console renders from -- it decides which controls exist, not whether a call is allowed. Enforcement stays at the interceptor. This read and the interceptor's RBAC leg resolve through the SAME bindings, so they cannot disagree about a binding-derived grant. They can still disagree in one direction, and it is worth stating plainly: authorization is an additive OR of the RBAC leg and the static coarse-scope leg, so a caller the interceptor admits on a coarse scope alone -- holding no binding -- resolves an empty set here. The admin scope is carved out below and unioned in; the other scope tokens are not, and neither is a management key riding delegated scopes. Such a caller sees fewer controls than it may in fact use. That is the safe direction (it hides, it never offers a control that 403s), but it is not "identical". resolved reports whether the frontier was actually computed. It is never a silent empty: a resolve failure answers an error rather than an empty permission list, because "no permissions" and "could not tell" render the same way and only one of them is safe to act on.

Request fields:

FieldRequiredDescription
customer_idnoCustomer scope to resolve within. Optional: empty resolves to the caller's default customer (their oldest project membership), as ListMyProjects does.
project_idnoProject to resolve at. Empty resolves at the customer's ORG level, which is a different question, not a broader one: an org-level grant that does not inherit to projects appears here and not in a project resolution, and a project-scoped grant appears only in its own project.

Response fields:

FieldRequiredDescription
resolvedoutput-onlyTrue when the frontier was computed. A resolve failure errors instead of returning false with an empty list, so this is informational for callers that mirror the field rather than a branch they must take.
scopeoutput-only"org" or "project" -- which target the permissions were resolved at.
project_idoutput-onlyEcho of the resolved project, empty for an org resolution.
permissionsoutput-onlyThe caller's permission atoms at that target, sorted and de-duplicated.
 
{"signatures":{"go":"func (x *MeClient) ResolveMyPermissions(ctx context.Context, req *identityv1.ResolveMyPermissionsRequest) (*identityv1.ResolveMyPermissionsResponse, error)","python":"resolve_my_permissions(req: identity_service_pb2.ResolveMyPermissionsRequest) -\u003e ResolveMyPermissionsResponse","typescript":"resolveMyPermissions(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ResolveMyPermissionsRequestSchema\u003e): Promise\u003cResolveMyPermissionsResponse\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/permissions\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ResolveMyPermissionsRequest{}\n\n\tresp, err := client.Me().ResolveMyPermissions(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/resolvemypermissions\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ResolveMyPermissionsRequest()\ntry:\n    result = client.me.resolve_my_permissions(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.resolveMyPermissions(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/permissions\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/me/permissions","slug":"resolve-my-permissions"}

List my reachable project ids

Changed in v0.5.0 (new features): The management plane now serves the RBAC read surface directly: a caller can resolve their own permissions at an organization or project, list the project ids they can reach, and read the deployment's permission catalog. These answer from the same bindings the platform already enforces against, so what the API reports and what a request is allowed to do cannot drift apart. Nothing changes for existing callers yet -- the console continues to use the auth service until it is moved over.

What it does: Returns the bare project ids the calling identity can reach in one customer, carrying read access. ListMyProjects answers the same frontier with full project records and a role per project; this returns only the ids, because the console's project scoping splices them into a query and never reads the rest. all_projects reports an org-wide grant, where the caller reaches every project in the customer and the id list is therefore empty rather than exhaustive.

Request fields:

FieldRequiredDescription
customer_idnoCustomer scope to list within. Optional: empty resolves to the caller's default customer.

Response fields:

FieldRequiredDescription
resolvedoutput-onlyTrue when the frontier was computed; a failure errors rather than returning an empty list, for the same reason as ResolveMyPermissions.
all_projectsoutput-onlyTrue when an org-scoped grant admits every project in the customer. The id list is then EMPTY because it is not an enumeration -- a caller that ignores this flag and reads only the ids sees "no projects" for exactly the callers who reach the most.
project_idsoutput-onlyBare project ids (no customer prefix), sorted. Empty when all_projects.
 
{"signatures":{"go":"func (x *MeClient) ListMyReachableProjects(ctx context.Context, req *identityv1.ListMyReachableProjectsRequest) (*identityv1.ListMyReachableProjectsResponse, error)","python":"list_my_reachable_projects(req: identity_service_pb2.ListMyReachableProjectsRequest) -\u003e ListMyReachableProjectsResponse","typescript":"listMyReachableProjects(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ListMyReachableProjectsRequestSchema\u003e): Promise\u003cListMyReachableProjectsResponse\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/reachable-projects\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ListMyReachableProjectsRequest{}\n\n\tresp, err := client.Me().ListMyReachableProjects(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/listmyreachableprojects\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ListMyReachableProjectsRequest()\ntry:\n    result = client.me.list_my_reachable_projects(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.listMyReachableProjects(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl \"${AGENTROUTER_BASE_URL}/v1/me/reachable-projects\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/me/reachable-projects","slug":"list-my-reachable-project-ids"}

Get the permission catalog

Changed in v0.5.0 (new features): The management plane now serves the RBAC read surface directly: a caller can resolve their own permissions at an organization or project, list the project ids they can reach, and read the deployment's permission catalog. These answer from the same bindings the platform already enforces against, so what the API reports and what a request is allowed to do cannot drift apart. Nothing changes for existing callers yet -- the console continues to use the auth service until it is moved over.

What it does: Returns the seeded permission vocabulary grouped by domain, for the surfaces that render a permission picker. The catalog grants nothing and is the same for every caller in a deployment, so it is authenticated but otherwise ungated -- matching the endpoint it replaces. It is sourced from authn.rbac_permission, which carries the atom, its domain and its scope set; the menu metadata and descriptions in fraser-auth's authored manifest do not reach the database and are not returned.

Request body: None.

Response fields:

FieldRequiredDescription
entriesoutput-onlyCatalog entries, one per domain, ordered by domain.
 
{"signatures":{"go":"func (x *MeClient) GetPermissionCatalog(ctx context.Context, req *identityv1.GetPermissionCatalogRequest) (*identityv1.GetPermissionCatalogResponse, error)","python":"get_permission_catalog(req: identity_service_pb2.GetPermissionCatalogRequest) -\u003e GetPermissionCatalogResponse","typescript":"getPermissionCatalog(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.GetPermissionCatalogRequestSchema\u003e): Promise\u003cGetPermissionCatalogResponse\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/permissions/catalog\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.GetPermissionCatalogRequest{}\n\n\tresp, err := client.Me().GetPermissionCatalog(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/getpermissioncatalog\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.GetPermissionCatalogRequest()\ntry:\n    result = client.me.get_permission_catalog(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.getPermissionCatalog(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl \"${AGENTROUTER_BASE_URL}/v1/permissions/catalog\" \\\n  -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/permissions/catalog","slug":"get-the-permission-catalog"}

Create a user

Changed in v0.5.0 (new features): Self-serve sign-up now works against the management plane: confirm the emailed link once to verify and sign in (a second open does not mint another session). Where a challenge is configured, sign-up and sign-in ask for it; an unreachable challenge service blocks sign-up but lets sign-in continue. Needs ENABLE_PASSWORD_AUTH with corporate login off, and SMTP_HOST; sign-up itself stays off unless turned on.

What it does: Provisions a user identity (an authn.user row). Admin-scoped and session-only: only platform operators (admin scope) acting through an interactive session may create users; API keys are rejected. Intended for tenant onboarding where users do not arrive via interactive SSO. When issue_session is true a session is also created and its token returned ONCE, so the caller can immediately act as the new user.

Request fields:

FieldRequiredDescription
emailnoEmail is the unique identity key (authn.user.email). Required; validated by the handler.
namenoDisplay name. Defaults to the email local-part when empty.
issue_sessionnoWhen true, also create a session and return its token once, so the caller can immediately act AS the new user (provisioning / automated tests).
initial_passwordnoOptional initial password. Stored in the same format the auth service writes, so the user can sign in on either stack.
send_password_setup_emailnoWhen true, email the new user a link to set their own password. Mutually exclusive with initial_password: an administrator either sets one or lets the user choose, never both.

Response fields:

FieldRequiredDescription
identity_idnoThe created (or existing, idempotent-by-email) identity id (authn.user.id).
emailnoundocumented
session_tokennoSet ONLY when issue_session was true; returned exactly once.
 
{"signatures":{"go":"func (x *MeClient) CreateUser(ctx context.Context, req *identityv1.CreateUserRequest) (*identityv1.CreateUserResponse, error)","python":"create_user(req: identity_service_pb2.CreateUserRequest) -\u003e CreateUserResponse","typescript":"createUser(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.CreateUserRequestSchema\u003e): Promise\u003cCreateUserResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/users\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"name\": \"...\",\n    \"issue_session\": false,\n    \"initial_password\": \"...\",\n    \"send_password_setup_email\": false\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithSessionToken(os.Getenv(\"AGENTROUTER_SESSION_TOKEN\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.CreateUserRequest{}\n\n\tresp, err := client.Me().CreateUser(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/createuser\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    session_token=os.environ[\"AGENTROUTER_SESSION_TOKEN\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.CreateUserRequest()\ntry:\n    result = client.me.create_user(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_SESSION_TOKEN in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  sessionToken: process.env.AGENTROUTER_SESSION_TOKEN,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.createUser(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/users\" \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"...\",\n    \"name\": \"...\",\n    \"issue_session\": false,\n    \"initial_password\": \"...\",\n    \"send_password_setup_email\": false\n  }'"},"persona":"Dashboard user (session token)","httpVerb":"POST","httpPath":"/v1/users","slug":"create-a-user"}

Start corporate SSO login

Changed in v0.5.0 (new features): Corporate SSO can now be registered and used through the management API. Administrators holding sso_providers permissions can create, read and delete the OIDC provider, a sign-in page can ask whether corporate login is available before anyone signs in, and a browser can complete a corporate login against the management API itself. Set SSO_CALLBACK_BASE_URL to the management API's public origin to enable the browser flow.

Changed in v0.5.0 (new features): Corporate SSO now supports SAML 2.0 as well as OIDC. Register the IdP entity id, sign-on URL and signing certificate, then import the service provider metadata the management API publishes for that provider. Encrypted assertions and IdP-initiated sign-in are not supported.

What it does: Opens the browser-shaped corporate SSO flow. Login hands PKCE orchestration to the CLI, which owns the loopback redirect; a browser has nowhere to keep a verifier, so this mints the whole attempt server-side and signs the return URL into the state. Any replica can then complete the callback -- no shared store, no session affinity (the reason login state is stateless at all, fraser#5339). Public of necessity: it runs before anyone is signed in.

Request fields:

FieldRequiredDescription
provider_idnoProvider to authenticate against. Empty selects the deployment default ("corporate", the id fraser-auth's SSO_PROVIDER_ID also defaults to).
return_urlyesAbsolute URL the browser is returned to once the session cookie is set. Validated against the configured allowed origins -- an unlisted origin is refused rather than quietly rewritten, so this can never become an open redirect out of an authenticated origin.

Response fields:

FieldRequiredDescription
authorization_urloutput-onlyURL the browser follows to the upstream IdP.
stateoutput-onlySigned, self-contained state echoed by the IdP and verified by the browser callback. Carries the return URL and an expiry, nothing secret.
 
{"signatures":{"go":"func (x *MeClient) StartSSOLogin(ctx context.Context, req *identityv1.StartSSOLoginRequest) (*identityv1.StartSSOLoginResponse, error)","python":"start_sso_login(req: identity_service_pb2.StartSSOLoginRequest) -\u003e StartSSOLoginResponse","typescript":"startSSOLogin(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.StartSSOLoginRequestSchema\u003e): Promise\u003cStartSSOLoginResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/sso/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"provider_id\": \"...\",\n    \"return_url\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.StartSSOLoginRequest{}\n\n\tresp, err := client.Me().StartSSOLogin(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/startssologin\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.StartSSOLoginRequest()\ntry:\n    result = client.me.start_sso_login(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.startSSOLogin(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/sso/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"provider_id\": \"...\",\n    \"return_url\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/sso/start","slug":"start-corporate-sso-login"}

Get SSO provider status

Changed in v0.5.0 (new features): Corporate SSO can now be registered and used through the management API. Administrators holding sso_providers permissions can create, read and delete the OIDC provider, a sign-in page can ask whether corporate login is available before anyone signs in, and a browser can complete a corporate login against the management API itself. Set SSO_CALLBACK_BASE_URL to the management API's public origin to enable the browser flow.

What it does: Reports whether a provider is configured and enabled and which protocol it speaks. Public and deliberately thin: a sign-in page has to ask before anyone is signed in, so the response carries no issuer, no client id and no endpoints -- only enough to decide whether to offer the corporate button.

Request fields:

FieldRequiredDescription
provider_idnoProvider to probe. Empty selects the deployment default.

Response fields:

FieldRequiredDescription
configuredoutput-onlyWhether a row exists for this provider id at all.
enabledoutput-onlyWhether that row is enabled. False when configured is false.
provider_typeoutput-only"oidc" or "saml". Empty when configured is false.
 
{"signatures":{"go":"func (x *MeClient) GetSSOProviderStatus(ctx context.Context, req *identityv1.GetSSOProviderStatusRequest) (*identityv1.GetSSOProviderStatusResponse, error)","python":"get_sso_provider_status(req: identity_service_pb2.GetSSOProviderStatusRequest) -\u003e GetSSOProviderStatusResponse","typescript":"getSSOProviderStatus(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.GetSSOProviderStatusRequestSchema\u003e): Promise\u003cGetSSOProviderStatusResponse\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/sso-providers/01H.../status\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.GetSSOProviderStatusRequest{}\n\n\tresp, err := client.Me().GetSSOProviderStatus(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/getssoproviderstatus\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.GetSSOProviderStatusRequest()\ntry:\n    result = client.me.get_sso_provider_status(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.getSSOProviderStatus(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl \"${AGENTROUTER_BASE_URL}/v1/sso-providers/01H.../status\""},"persona":"Public (no credential required)","httpVerb":"GET","httpPath":"/v1/sso-providers/{provider_id}/status","slug":"get-sso-provider-status"}

Start social login

Changed in v0.5.0 (new features): Google and GitHub sign-in can now be served by the management API. Set the provider's client id and secret to offer it; a provider missing either one is not offered. A Google or GitHub account whose email address the provider has not verified cannot sign in.

What it does: Opens a Google or GitHub login, the same browser shape as StartSSOLogin and with the same signed state. Corporate SSO and social login differ in where the provider is configured, not in how the flow runs: corporate is a row an administrator registers at runtime, while the social apps are deployment credentials supplied as environment variables, because their client secrets belong to the operator rather than to a tenant. That is why this takes a provider NAME from a closed set instead of a provider id. Public of necessity: it runs before anyone is signed in.

Request fields:

FieldRequiredDescription
provideryes"google" or "github". Required: unlike corporate SSO there is no single deployment default to fall back to.
return_urlyesAbsolute URL the browser is returned to once the session cookie is set. Checked against the same allowed origins StartSSOLogin checks.

Response fields:

FieldRequiredDescription
authorization_urloutput-onlyURL the browser follows to the social provider.
stateoutput-onlySigned, self-contained state echoed by the provider and verified by the callback. Carries the return URL and an expiry, nothing secret.
 
{"signatures":{"go":"func (x *MeClient) StartSocialLogin(ctx context.Context, req *identityv1.StartSocialLoginRequest) (*identityv1.StartSocialLoginResponse, error)","python":"start_social_login(req: identity_service_pb2.StartSocialLoginRequest) -\u003e StartSocialLoginResponse","typescript":"startSocialLogin(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.StartSocialLoginRequestSchema\u003e): Promise\u003cStartSocialLoginResponse\u003e","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/social/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"provider\": \"...\",\n    \"return_url\": \"...\"\n  }'"},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.StartSocialLoginRequest{}\n\n\tresp, err := client.Me().StartSocialLogin(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/startsociallogin\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.StartSocialLoginRequest()\ntry:\n    result = client.me.start_social_login(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.startSocialLogin(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/auth/social/start\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"provider\": \"...\",\n    \"return_url\": \"...\"\n  }'"},"persona":"Public (no credential required)","httpVerb":"POST","httpPath":"/v1/auth/social/start","slug":"start-social-login"}

List available social logins

Changed in v0.5.0 (new features): Google and GitHub sign-in can now be served by the management API. Set the provider's client id and secret to offer it; a provider missing either one is not offered. A Google or GitHub account whose email address the provider has not verified cannot sign in.

What it does: Names the social logins this deployment has credentials for, so a sign-in page renders the buttons that will actually work. Public and thin for the same reason GetSSOProviderStatus is: it carries no client id and no secret, only the names.

Request body: None.

Response fields:

FieldRequiredDescription
providersoutput-onlyNames of the configured providers, e.g. ["google", "github"]. Empty when the deployment has registered no social apps.
 
{"signatures":{"go":"func (x *MeClient) ListSocialProviders(ctx context.Context, req *identityv1.ListSocialProvidersRequest) (*identityv1.ListSocialProvidersResponse, error)","python":"list_social_providers(req: identity_service_pb2.ListSocialProvidersRequest) -\u003e ListSocialProvidersResponse","typescript":"listSocialProviders(req: MessageInitShape\u003ctypeof tars_identity_v1_identity_service_pb.ListSocialProvidersRequestSchema\u003e): Promise\u003cListSocialProvidersResponse\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/auth/social/providers\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tidentityv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/identity/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026identityv1.ListSocialProvidersRequest{}\n\n\tresp, err := client.Me().ListSocialProviders(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/me/listsocialproviders\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.identity.v1 import identity_service_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n    base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n    api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = identity_service_pb2.ListSocialProvidersRequest()\ntry:\n    result = client.me.list_social_providers(req)\n    print(result)\nexcept Exception as err:\n    print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n#   agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n  baseUrl: process.env.AGENTROUTER_BASE_URL,\n  apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n  const result = await client.me.listSocialProviders(req)\n  console.log(result)\n} catch (err) {\n  console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n  \"name\": \"me\",\n  \"version\": \"0.1.0\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^20.0.0\",\n    \"typescript\": \"^5.4.0\"\n  }\n}\n"},{"name":"tsconfig.json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true\n  }\n}\n"}]},"curl":"curl \"${AGENTROUTER_BASE_URL}/v1/auth/social/providers\""},"persona":"Public (no credential required)","httpVerb":"GET","httpPath":"/v1/auth/social/providers","slug":"list-available-social-logins"}