Sign in and start a session

Session · POST /v1/sessions · MCP tool login

Exchanges your login name and secret for a session. Send the session in the X-Tarsana-Session header on every later call. An API access token is not accepted here; after you sign in, you can create one with issue-access-token.

You do not need to sign in.

Parameters

Name	In	Required	Description
`login`	body	yes	Your login name
`secret`	body	yes	Your login secret

Returns

A JSON object with these keys: session, login, scopes, tenants, expires_at, guarantee, caller_authenticated.

Example request

curl -X POST https://api.tarsana.io/v1/sessions \
  -H "Content-Type: application/json" \
  --data '{"login": "you@example.com", "secret": "YOUR-LOGIN-SECRET"}'

Example response

{
  "session": "YOUR-SESSION",
  "login": "you@example.com",
  "scopes": [
    "operate",
    "read",
    "submit"
  ],
  "tenants": [
    "acme"
  ],
  "expires_at": "2026-10-05T03:15:39Z",
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`rate_limited`	429	You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again.
`surface_fault`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown