Organizations, team & API keys

Manage organizations (workspaces), their members, roles, departments, and API keys. See Team & workplace for the concepts. These are Dashboard API endpoints — they use the { success, data } envelope and require a user JWT. Unlike most of the Dashboard API, the /api/orgs/* routes do not accept an API key — these are user‑facing administration actions, so you must be a signed‑in member.

Organizations

Method	Path	Purpose
`GET`	`/api/orgs`	List organizations you belong to
`POST`	`/api/orgs`	Create an organization (you become owner)
`GET`	`/api/orgs/{id}`	Organization details
`PUT`	`/api/orgs/{id}`	Update (name, plan, settings)
`DELETE`	`/api/orgs/{id}`	Delete (owner only)

curl -X POST https://api.telenow.ai/api/orgs \
  -H "Authorization: Bearer eyJ…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Inc" }'

Organization settings (via PUT) include the workspace name, plan, currency, white‑label subdomain (see White‑label & branding), missed‑call message, and default dial number.

Members & invitations

Method	Path	Purpose
`GET`	`/api/orgs/{id}/members`	List members
`POST`	`/api/orgs/{id}/invite`	Invite a user by email
`POST`	`/api/orgs/{id}/role`	Change a member's role
`PUT`	`/api/orgs/{id}/members/{userId}`	Update member (e.g. allocated number)
`DELETE`	`/api/orgs/{id}/members/{userId}`	Remove a member
`GET`	`/api/orgs/{id}/invitations`	List outstanding invitations
`DELETE`	`/api/orgs/{id}/invitations/{invId}`	Revoke an invitation
`POST`	`/api/orgs/accept/{token}`	Accept an invitation
`GET`	`/api/orgs/invitations/mine`	Invitations waiting on the caller
`POST`	`/api/orgs/invitations/{invId}/accept`	Join the org that invited you
`POST`	`/api/orgs/invitations/{invId}/decline`	Turn an invitation down

Member management requires the owner or admin role. The three /invitations/… routes above are the invitee's own and need only a valid JWT — the caller is not a member of the inviting org yet.

POST /api/orgs/{id}/invite has two outcomes, given by status in the response:

active — the address had no account. One is created and added immediately, and generatedPassword is returned once so you can share it.
pending — the address already has an account. That person is invited and joins when they accept; userId and generatedPassword are omitted.

A user can belong to any number of organizations. Callers pick the active one per request with the X-Org-Id header — it is never baked into the JWT.

Roles & departments

Method	Path	Purpose
`GET`/`POST`	`/api/orgs/{id}/roles`	List / create custom roles
`PUT`/`DELETE`	`/api/orgs/{id}/roles/{roleId}`	Update / delete a role
`GET`/`POST`	`/api/orgs/{id}/departments`	List / create departments
`DELETE`	`/api/orgs/{id}/departments/{deptId}`	Delete a department

API keys

API keys authenticate server‑to‑server and automation calls — see Authentication for how they're used and the create flow in the dashboard. These management endpoints require a user JWT; the org is taken from the {orgId} in the path (no X-Org-Id header needed), and RBAC is enforced per action.

Method	Path	Required role	Purpose
`GET`	`/api/orgs/{orgId}/api-keys`	any member	List keys
`POST`	`/api/orgs/{orgId}/api-keys`	owner / admin / developer	Create a key (secret returned once)
`DELETE`	`/api/orgs/{orgId}/api-keys/{keyId}`	owner / admin	Revoke a key

List keys

curl https://api.telenow.ai/api/orgs/{orgId}/api-keys \
  -H "Authorization: Bearer eyJ…"

{
  "success": true,
  "data": {
    "apiKeys": [
      {
        "id": "…", "org_id": "…", "name": "Production backend",
        "last_four": "abcd", "role": "developer", "created_by": "…",
        "last_used_at": "2026-06-12T08:00:00Z", "revoked_at": null,
        "created_at": "2026-06-01T10:00:00Z"
      }
    ],
    "total": 1
  }
}

Only the last_four digits of each key are returned — the full secret is never retrievable after creation.

Create a key

curl -X POST https://api.telenow.ai/api/orgs/{orgId}/api-keys \
  -H "Authorization: Bearer eyJ…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production backend", "role": "developer" }'

name is required; role is optional and defaults to developer. The response includes the full secret once — store it immediately:

{
  "success": true,
  "data": {
    "key": { "id": "…", "name": "Production backend", "role": "developer", "last_four": "abcd", "…": "…" },
    "secret": "vai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Revoke a key

curl -X DELETE https://api.telenow.ai/api/orgs/{orgId}/api-keys/{keyId} \
  -H "Authorization: Bearer eyJ…"

Returns { "success": true, "message": "api key revoked" }. Revocation is immediate.

Tips

Give each integration its own key. Revoking one then won't break the others, and the audit log will attribute each action to the correct key.
Use the dashboard's Developers → API keys page to see each key's last‑used time — handy for finding stale keys to retire.
See Team & workplace for the roles, departments, and number‑allocation model in the UI, and the Audit log API to review who changed org settings or keys.