The Togetha API and signing in from another app

Every Togetha application - the dashboard, the mobile app, YourGaff and anything you build - signs in through the same place: Togetha Connect. You get back one access token, and that single token works against both the REST API and the MCP server.

Base URL: https://app.togetha.co.uk

Three ways to get a token

Pick the one that matches who is signing in.

From the dashboard

The quickest way, and the one to use when you are setting something up by hand: sign in to Togetha and go to Settings -> Developer. Give the token a name, tick the scopes it needs, and create it.

The token is shown once, at the moment it is created - Togetha only stores its hash, so copy it there and then. The same screen lists every token you hold, when it was last used, and lets you revoke any of them.

Machine to machine

When your service already holds the user's Togetha credentials, or you are scripting against your own account, ask for a token directly:

curl -X POST https://app.togetha.co.uk/api/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "clientId": "togetha-dashboard",
    "scope": "read write mcp"
  }'

The response carries the token, when it expires, the organisation it is scoped to, and every organisation you could have picked instead:

{
  "accessToken": "oat_...",
  "tokenType": "Bearer",
  "expiresAt": "2026-09-29T10:15:00.000Z",
  "scopes": ["read", "write", "mcp"],
  "org": { "id": "zr8LXU...", "name": "Clifton Home org", "role": "owner" },
  "organisations": [],
  "mcpEndpoint": "https://app.togetha.co.uk/api/v2/mcp"
}

Pass orgId in the request to scope the token to a specific workspace. Leave it out and your first organisation is used.

Browser sign in

When a real person is connecting your app to their Togetha account, send them to the hosted sign-in page instead. They never type their Togetha password into your app.

1. Send the user to https://app.togetha.co.uk/connect with client_id, redirect_uri, scope and an optional state you want echoed back.
2. They sign in on a Togetha page that shows your app's name and exactly what it is asking for.
3. Togetha redirects to your redirect_uri with a single-use code (and your state).
4. Exchange the code for a token.

curl -X POST https://app.togetha.co.uk/api/v2/auth/token/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "the-code-from-the-redirect",
    "clientId": "your-client-id",
    "redirectUri": "https://your-app.example.com/callback"
  }'

Codes are single use and expire after five minutes. Your redirect_uri must be registered against your client, so a stolen client_id cannot be used to send tokens somewhere else.

Scopes

• read - properties, tenancies, sales, maintenance, finance, contacts and tasks.
• write - create notes, tasks and maintenance requests, and update maintenance status. Nothing can be archived or deleted with an API token.
• mcp - connect to the Togetha MCP server so an AI agent can query the workspace.

A token only ever gets the scopes its client is registered for.

Using the token

Send it as a bearer token on every request:

curl https://app.togetha.co.uk/api/v2/leases/all \
  -H "Authorization: Bearer oat_..."

The token is pinned to one organisation, so you never pass an organisation id - the API scopes every query for you.

Checking and revoking a token

# Who is this token for, and is it still good?
curl https://app.togetha.co.uk/api/v2/auth/me \
  -H "Authorization: Bearer oat_..."

# Sign out - revoke the token you are calling with
curl -X POST https://app.togetha.co.uk/api/v2/auth/token/revoke \
  -H "Authorization: Bearer oat_..."

/auth/me returns the user, the organisation the token is scoped to, the granted scopes, the client that requested it and the expiry. Revoke a token whenever a user disconnects your app.

You can also revoke any token from Settings -> Developer in the dashboard. Revoking takes effect immediately - whatever was using that token stops working on its next request.

What the API covers

• Properties - /api/v2/properties - properties, units, rooms, photos and documents.
• Tenancies - /api/v2/leases - leases, tenants, booking forms, signing and references.
• Sales - /api/v2/sales - sales, buyers, offer letters and instalments.
• Maintenance - /api/v2/maintenance - repair tickets and contractor assignment.
• Finance - /api/v2/finance - payments, expenses, payouts and invoices.
• Contacts - /api/v2/contacts - contractors, buyers, landlords and suppliers.
• Tasks - /api/v2/tasks - task boards and task items.
• Search - /api/v2/search/global - fuzzy search across everything above.

Discovery

If all you know is the hostname, ask Togetha where everything lives:

curl https://app.togetha.co.uk/.well-known/togetha-connect

That returns the sign-in, token, exchange, revocation and introspection endpoints, the MCP endpoint, and the scopes this deployment supports.

Registering your application

First-party Togetha apps are registered already. To add your own, get in touch at [email protected] with your app name, the redirect URLs it will use, and the scopes it needs.

Tokens last 30 days. Treat them like passwords: store them server side, never in client-side code or a public repository.