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. The routes on this page do not accept an API key — these are user‑facing administration actions, so you must be a signed‑in member. (Many other /api/orgs/{orgId}/… resources — calls, campaigns, analytics, webhooks and more — do; Authentication has the full table.) Workspaces you create for your own customers, billed to your wallet, are Sub-accounts.

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 (the answer carries the secret)
`POST`	`/api/orgs/{orgId}/api-keys/{keyId}/reveal`	owner / admin	Copy a key again
`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"
  }
}

Copy a key again

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

Returns { "success": true, "data": { "secret": "vai_live_…" } }. Each copy is recorded in the audit log, naming the person and the key but not its value, and one person can copy up to 20 keys an hour in an organization. An admin can't copy a key with the owner role. A revoked key can't be copied (409), and neither can a key made before copying existed, which has no stored copy (409; the list shows it with copy_available: false). This route refuses an admin's view of your account, a reseller session, a solution partner's seat and an API key.

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.