Account

Self-service endpoints for agents to manage their own profile, teams, devices, and session. All endpoints require a valid JWT token with the agent-api audience (obtained via Agent Login).

Endpoints

Method	Endpoint	Description
`GET`	`/me`	Get my profile
`GET`	`/me/teams`	List my teams
`GET`	`/me/teams/:id/agents`	List other agents in my team
`PATCH`	`/me`	Update my display name
`PATCH`	`/me/avatar`	Upload/change avatar
`PATCH`	`/me/password`	Change my password
`POST`	`/me/devices/voip-push-token`	Register VoIP push notification token
`POST`	`/me/devices/notification-push-token`	Register notification push token
`GET`	`/me/devices`	List my registered devices
`POST`	`/me/logout`	Logout and remove device token

Agent Profile Object

The profile object returned by /me endpoints:

Field	Type	Description
`id`	string	Unique agent ID (prefixed with `ag_`)
`username`	string	Agent login username
`display_name`	string	Agent display name
`email`	string \| null	Agent email address
`avatar`	string \| null	Avatar image URL
`state`	string	Real-time presence: `available`, `incall`, `busy`, `offline`
`is_active`	boolean	Whether the agent account is active
`workspace_id`	string	Workspace identifier
`domain`	string	Agent's SIP domain
`country_code`	string	ISO 3166-1 alpha-2 country code
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

Get My Profile

GET /me

Retrieve the current authenticated agent's profile.

Authentication

Requires Bearer JWT with agent-api audience.

Request

curl -X GET "https://{workspace_id}.firetell.app/api/v1/me" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"

Response `200 OK`

{
  "id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
  "username": "johndoe",
  "display_name": "John Doe",
  "email": "john@example.com",
  "avatar": "https://storage.firetell.app/avatars/ag_7f3a2b1c.jpg",
  "role": "member",
  "state": "available",
  "is_active": true,
  "workspace_id": "my_workspace",
  "domain": "my_workspace.app.firetell.com",
  "country_code": "VN",
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-07-13T09:00:00.000Z"
}

Error Responses

Status	Description
`403`	JWT audience is not `agent-api`
`404`	Agent profile not found or account is not active

List My Teams

GET /me/teams

Retrieve a paginated list of teams that the current agent belongs to.

Authentication

Requires Bearer JWT with agent-api audience.

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (min: 1)
`limit`	number	`10`	Items per page (min: 1, max: 100)

Request

curl -X GET "https://{workspace_id}.firetell.app/api/v1/me/teams?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"

Response `200 OK`

{
  "data": [
    {
      "team_id": "te_a1b2c3d4e5f6g7h8",
      "team": {
        "id": "te_a1b2c3d4e5f6g7h8",
        "title": "Support Team",
        "workspace_id": "my_workspace",
        "agent_count": 5
      }
    },
    {
      "team_id": "te_x9y8z7w6v5u4t3s2",
      "team": {
        "id": "te_x9y8z7w6v5u4t3s2",
        "title": "Sales Team",
        "workspace_id": "my_workspace",
        "agent_count": 3
      }
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

Item Fields

Field	Type	Description
`team_id`	string	Team ID
`team`	object	Team details (id, title, agent_count)

info

Agent roles are no longer stored per-team. Each agent has a single workspace-level role (agent, leader, or supervisor) set by an admin. See Roles & Permissions for details.

Error Responses

Status	Description
`403`	JWT audience is not `agent-api`
`404`	Agent profile not found or account is not active

List Team Agents

GET /me/teams/:id/agents

Retrieve a paginated list of other agents in a team that you belong to. The current agent is excluded from the results. This endpoint is designed for displaying teammate lists for messaging or calling.

Authentication

Requires Bearer JWT with agent-api audience.

Path Parameters

Parameter	Type	Description
`id`	string	Team ID (e.g. `te_a1b2c3d4e5f6g7h8`)

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (min: 1)
`limit`	number	`10`	Items per page (min: 1, max: 100)

Request

curl -X GET "https://{workspace_id}.firetell.app/api/v1/me/teams/te_a1b2c3d4e5f6g7h8/agents?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"

Response `200 OK`

{
  "data": [
    {
      "username": "jane_smith",
      "display_name": "Jane Smith",
      "avatar": "https://storage.firetell.app/avatars/ag_x9y8z7.jpg",
      "state": "available",
      "role": "leader"
    },
    {
      "username": "bob_wilson",
      "display_name": "Bob Wilson",
      "avatar": null,
      "state": "incall",
      "role": "member"
    },
    {
      "username": "alice_chen",
      "display_name": "Alice Chen",
      "avatar": "https://storage.firetell.app/avatars/ag_m3n4o5.jpg",
      "state": "offline",
      "role": "member"
    }
  ],
  "meta": {
    "total": 4,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

Item Fields

Field	Type	Description
`username`	string	Agent username
`display_name`	string	Agent display name
`avatar`	string \| null	Avatar URL
`state`	string	Presence state: `available`, `incall`, `busy`, `offline`
`role`	string	Agent's workspace-level role: `agent`, `leader`, or `supervisor`

info

The role field reflects the agent's account-level role, not a team-specific role. Roles are assigned globally per agent by workspace admins.

Error Responses

Status	Description
`403`	You are not a member of this team
`404`	Agent profile not found or account is not active

Update My Profile

PATCH /me

Update the current agent's display name. Only display_name can be modified by the agent. Other fields like username, email, is_active, and country_code can only be changed by workspace admins via the Agents API.

Authentication

Requires Bearer JWT with agent-api audience.

Request Body

Field	Type	Description
`display_name`	string	Display name (1–35 characters, letters and spaces only)

Request

curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/me" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "John D."
  }'

Response `200 OK`

Returns the updated agent profile object.

Error Responses

Status	Description
`403`	JWT audience is not `agent-api`
`404`	Agent profile not found or account is not active

Upload / Change Avatar

PATCH /me/avatar

Upload or replace the current agent's avatar image. The previous avatar (if any) is automatically deleted from storage.

Authentication

Requires Bearer JWT with agent-api audience.

Request Body

Send as multipart/form-data with a single file field:

Field	Type	Required	Description
`file`	file	✅	Image file (max 5MB, must be an image format)

Request

curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/me/avatar" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -F "file=@/path/to/avatar.jpg"

Response `200 OK`

Returns the updated agent profile object with the new avatar URL.

Error Responses

Status	Description
`400`	File is missing or not an image format
`403`	JWT audience is not `agent-api`
`404`	Agent profile not found or account is not active

Change My Password

PATCH /me/password

Change the current agent's login password. Unlike the admin Change Password endpoint, this requires the current password for verification.

Authentication

Requires Bearer JWT with agent-api audience.

Request Body

Field	Type	Required	Description
`current_password`	string	✅	Current (old) password
`new_password`	string	✅	New password (6–50 characters)

Request

curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/me/password" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "oldPassword123",
    "new_password": "newSecurePassword456"
  }'

Response `200 OK`

{
  "message": "Password changed successfully"
}

Error Responses

Status	Description
`401`	Current password is incorrect
`403`	JWT audience is not `agent-api`
`404`	Agent profile not found or account is not active

caution

After changing the password, the agent's existing JWT tokens remain valid until expiration. No active sessions are terminated. The new password takes effect on the next login.

Register VoIP Push Notification Token

POST /me/devices/voip-push-token

Register or update a VoIP push notification token for the current device. This enables the agent to receive incoming call notifications via VoIP Push (APNs VoIP / FCM) even when the app is in the background or the WebSocket connection is closed.

If a device with the same device_id already exists, it will be updated with the new token and metadata.

info

This endpoint registers the VoIP push token used for incoming call pushes. To register a token for regular notifications (e.g., messages, alerts), use POST /me/devices/notification-push-token instead. The device record is created or updated (upserted by device_id).

On iOS, VoIP push (APNs VoIP) and regular push (APNs standard) use different tokens. Both must be registered separately. On Android/Web, FCM handles both types — you may use the same FCM token for both endpoints.

Authentication

Requires Bearer JWT with agent-api audience.

Request Body

Field	Type	Required	Description
`push_token`	string	✅	Push notification token (APNs VoIP token or FCM token)
`device_id`	string	✅	Unique device identifier (e.g., IDFV on iOS, Android ID)
`platform`	string	✅	Device platform: `ios`, `android`, or `web`
`os_version`	string		OS version (e.g., `"17.5.1"`, `"14"`)
`app_version`	string		Application version (e.g., `"1.2.0"`)
`device_model`	string		Device model (e.g., `"iPhone 15 Pro"`, `"Galaxy S24"`)

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/me/devices/voip-push-token" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "push_token": "abc123...xyz",
    "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
    "platform": "ios",
    "os_version": "17.5.1",
    "app_version": "1.2.0",
    "device_model": "iPhone 15 Pro"
  }'

Response `200 OK`

{
  "id": "dev_a1b2c3d4e5f6g7h8",
  "workspace_id": "my_workspace",
  "username": "johndoe",
  "push_token": "abc123...xyz",
  "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "platform": "ios",
  "os_version": "17.5.1",
  "app_version": "1.2.0",
  "device_model": "iPhone 15 Pro",
  "voip_enabled": true,
  "notification_push_token": null,
  "last_active_at": "2026-07-13T10:00:00.000Z",
  "created_at": "2026-07-13T10:00:00.000Z",
  "updated_at": "2026-07-13T10:00:00.000Z"
}

tip

Call this endpoint every time the app launches or the push token refreshes to ensure the server always has the latest token. Stale tokens cannot receive push notifications.

Register Notification Push Token

POST /me/devices/notification-push-token

Register or update a regular push notification token for the current device. This enables the agent to receive non-VoIP notifications (e.g., chat messages, system alerts) via standard push (APNs / FCM).

The device must already be registered via POST /me/devices/voip-push-token.

info

On iOS, the standard APNs token is different from the VoIP APNs token. Both must be registered separately. On Android/Web, FCM handles both VoIP and regular push — the same token can be used.

Authentication

Requires Bearer JWT with agent-api audience.

Request Body

Field	Type	Required	Description
`notification_push_token`	string	✅	Regular push notification token (APNs standard or FCM)
`device_id`	string	✅	Unique device identifier (same as used in `/me/devices`)
`platform`	string	✅	Device platform: `ios`, `android`, or `web`

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/me/devices/notification-push-token" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_push_token": "def456...uvw",
    "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
    "platform": "ios"
  }'

Response `200 OK`

{
  "id": "dev_a1b2c3d4e5f6g7h8",
  "workspace_id": "my_workspace",
  "username": "johndoe",
  "push_token": "abc123...xyz",
  "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "platform": "ios",
  "os_version": "17.5.1",
  "app_version": "1.2.0",
  "device_model": "iPhone 15 Pro",
  "voip_enabled": true,
  "notification_push_token": "def456...uvw",
  "last_active_at": "2026-07-13T10:05:00.000Z",
  "created_at": "2026-07-13T10:00:00.000Z",
  "updated_at": "2026-07-13T10:05:00.000Z"
}

Error Responses

Status	Description
`403`	JWT audience is not `agent-api`
`404`	Device not found — register VoIP push token first via `POST /me/devices/voip-push-token`

tip

Call this endpoint after registering the VoIP push token, or whenever the notification push token refreshes. On iOS, register both tokens on app launch:

POST /me/devices/voip-push-token — with the VoIP APNs token
POST /me/devices/notification-push-token — with the standard APNs token

List My Devices

GET /me/devices

List all devices with registered push notification tokens for the current agent.

Authentication

Requires Bearer JWT with agent-api audience.

Response `200 OK`

[
  {
    "id": "dev_a1b2c3d4e5f6g7h8",
    "workspace_id": "my_workspace",
    "username": "johndoe",
    "push_token": "abc123...xyz",
    "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
    "platform": "ios",
    "os_version": "17.5.1",
    "app_version": "1.2.0",
    "device_model": "iPhone 15 Pro",
    "voip_enabled": true,
    "notification_push_token": "def456...uvw",
    "last_active_at": "2026-07-13T10:00:00.000Z"
  },
  {
    "id": "dev_x9y8z7w6v5u4t3s2",
    "workspace_id": "my_workspace",
    "username": "johndoe",
    "push_token": "def456...uvw",
    "device_id": "android-device-id-123",
    "platform": "android",
    "os_version": "14",
    "app_version": "1.2.0",
    "device_model": "Samsung Galaxy S24",
    "voip_enabled": true,
    "notification_push_token": "def456...uvw",
    "last_active_at": "2026-07-12T08:00:00.000Z"
  }
]

Logout

POST /me/logout

Logout from a specific device. This removes the push notification token for the specified device, preventing it from receiving further call notifications.

caution

Client applications MUST call this endpoint when the agent logs out. If the agent simply closes the app without calling logout, the server will continue attempting to send push notifications to the stale token, which wastes resources and may cause the push provider (APNs/FCM) to throttle or revoke the token.

Inactive device registrations are automatically cleaned up after 30 days of inactivity as a safety net, but explicit logout is always preferred.

Authentication

Requires Bearer JWT with agent-api audience.

Request Body

Field	Type	Required	Description
`device_id`	string	✅	The device identifier used during push token registration

Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/me/logout" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
  }'

Response `200 OK`

{
  "message": "Logged out successfully"
}

info

This endpoint is idempotent — calling it multiple times with the same device_id always returns success, even if the device was already unregistered.

What happens on logout

The push notification token for the specified device is deleted
If the agent has no more devices with push tokens and no active WebSocket connections, their presence state transitions to offline
The JWT token itself remains valid until expiration — logout only removes the push notification registration

Endpoints​

Agent Profile Object​

Get My Profile​

Authentication​

Request​

Response 200 OK​

Error Responses​

List My Teams​

Authentication​

Query Parameters​

Request​

Response 200 OK​

Item Fields​

Error Responses​

List Team Agents​

Authentication​

Path Parameters​

Query Parameters​

Request​

Response 200 OK​

Item Fields​

Error Responses​

Update My Profile​

Authentication​

Request Body​

Request​

Response 200 OK​

Error Responses​

Upload / Change Avatar​

Authentication​

Request Body​

Request​

Response 200 OK​

Error Responses​

Change My Password​

Authentication​

Request Body​

Request​

Response 200 OK​

Error Responses​

Register VoIP Push Notification Token​

Authentication​

Request Body​

Request​

Response 200 OK​

Register Notification Push Token​

Authentication​

Request Body​

Request​

Response 200 OK​

Error Responses​

List My Devices​

Authentication​

Response 200 OK​

Logout​

Authentication​

Request Body​

Request​

Response 200 OK​

What happens on logout​

Endpoints

Agent Profile Object

Get My Profile

Authentication

Request

Response `200 OK`

Error Responses

List My Teams

Authentication

Query Parameters

Request

Response `200 OK`

Item Fields

Error Responses

List Team Agents

Authentication

Path Parameters

Query Parameters

Request

Response `200 OK`

Item Fields

Error Responses

Update My Profile

Authentication

Request Body

Request

Response `200 OK`

Error Responses

Upload / Change Avatar

Authentication

Request Body

Request

Response `200 OK`

Error Responses

Change My Password

Authentication

Request Body

Request

Response `200 OK`

Error Responses

Register VoIP Push Notification Token

Authentication

Request Body

Request

Response `200 OK`

Register Notification Push Token

Authentication

Request Body

Request

Response `200 OK`

Error Responses

List My Devices

Authentication

Response `200 OK`

Logout

Authentication

Request Body

Request

Response `200 OK`

What happens on logout