Authentication

Manage authentication.

Retrieve metadata.

get

Retrieve system metadata information. If the optional domain query parameter is specified, the relevant tenant metadata information will be returned together. System metadata:

web_domain
private_ipv4
public_ipv4
enable_ipv6
private_ipv6
public_ipv6
primary_dns_server
secondary_dns_server
enable_dataflow Tenant metadata:
name
domain
website
avatar_url
enable_ms365_integration
ms365_authorization_endpoint

Query parameters

domainstringOptional

Use the domain query parameter to retrieve just a subset of a collection.

Responses

200

application/json

web_domainstringOptional

The web domain for PortSIP PBX

private_ipv4stringOptional

The private IPv4 of system.

public_ipv4stringOptional

The public IPv4 of system.

enable_ipv6booleanOptional

Indicates if IPv6 would be enabled.

Default: true

private_ipv6stringOptional

The private IPv6 of system.

public_ipv6stringOptional

The public IPv6 of system.

primary_dns_serverstringOptional

The primary DNS server.

secondary_dns_serverstringOptional

The secondary DNS server.

namestring · min: 1 · max: 1024Optional

The name of the tenant.

domainstring · min: 1 · max: 280Optional

The SIP domain of tenant.
It is usually a fully qualified domain name (FQDN). If there is no FQDN, you can also use the IP address of the PBX server as the SIP domain. The SIP domain name is only used for SIP message authentication and does not require analysis.

websitestring · max: 255Optional

The official website of tenant.

avatar_urlstringRead-onlyOptional

The relative path to file url for file downloading.

Example: /api/blobs/WexWdABcd5D4PDgzTKV3gAAAEu00WcK

enable_ms365_integrationbooleanOptional

Microsoft 365 SSO integration enabled or not.

ms365_authorization_endpointstringOptional

The Microsoft Identity Provider authorization endpoint for this tenant.

enable_dataflowbooleanOptional

Dataflow service enabled or not.

4XX

Error

get/info

GET /api/info HTTP/1.1
Host: HOSTNAME:8887
Accept: */*

{
  "web_domain": "example.com",
  "private_ipv4": "127.0.0.1",
  "public_ipv4": "127.0.0.1",
  "enable_ipv6": false,
  "private_ipv6": "::1",
  "public_ipv6": "::1",
  "primary_dns_server": "127.0.0.1",
  "secondary_dns_server": "127.0.0.1",
  "name": "example",
  "domain": "example.com",
  "website": "example.com",
  "avatar_url": "avatar.com/avatar",
  "enable_ms365_integration": false,
  "ms365_authorization_endpoint": "/ms365",
  "enable_dataflow": true
}

Sign in with credentials

post

Query parameters

qrbooleanOptionalDefault: false

Body

usernamestring · min: 1 · max: 64Required

The user's account name.
Only letters, numbers, and the following special characters can be added: underscore, dash, single quote, and period (_, -, ', and .).
Username cannot start or end with period (.).
admin, system, administrator, and root are reserved names for system admin only with case ignored.

passwordstringRequired

The password of user.

domainstring · min: 1 · max: 280Optional

Responses

200

application/json

4XX

Error

post/auth/sign_in

POST /api/auth/sign_in HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "username": null,
  "password": null,
  "domain": null
}

{
  "access_token": "xxxxxxxxxxx",
  "refresh_token": "xxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 1800
}

Sign in with social account

post

Path parameters

providerstringRequired

The name of IdP provider. Currently only supports microsoft.

Body

domainstring · min: 1 · max: 280Required

callback_urlstringRequired

The callback url for authentication flow.

Responses

200

application/json

urlstringOptional

The IdP authentication url.

4XX

Error

post/auth/sign_in/{provider}

POST /api/auth/sign_in/{provider} HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "domain": null,
  "callback_url": null
}

{
  "url": null
}

Sign out from system.

post

Sign out from system.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

No content

4XX

Error

post/auth/sign_out

POST /api/auth/sign_out HTTP/1.1
Host: HOSTNAME:8887
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Send OTP to email.

post

Request to send OTP to email.

Body

tokenstringRequired

The session token in authentication flow.

Responses

200

No content

4XX

Error

post/auth/send_otp

POST /api/auth/send_otp HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "token": null
}

No content

Verify OTP from email.

post

Request to verify OTP from email.

Body

tokenstringRequired

The session token in authentication flow.

codestringRequired

The OTP code in authentication flow.

Responses

200

No content

4XX

Error

post/auth/verify_otp

POST /api/auth/verify_otp HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "token": null,
  "code": null
}

No content

Initiate authentication forget password flow

post

Initiate authentication forget password flow.

Body

domainstring · min: 1 · max: 280Required

usernamestring · min: 1 · max: 64Required

callback_urlstringRequired

The callback url for authentication flow.

Responses

200

No content

4XX

Error

post/auth/forget_password

POST /api/auth/forget_password HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "domain": null,
  "username": null,
  "callback_url": null,
  "required": null
}

No content

Reset password with session token.

post

Reset password with session token.

Body

tokenstringRequired

The session token in authentication flow.

new_passwordstringRequired

The password of user.

Responses

200

No content

4XX

Error

post/auth/reset_password

POST /api/auth/reset_password HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "token": null,
  "new_password": null
}

No content

Refresh the access token.

post

Refresh the access token.

Body

refresh_tokenstringRequired

The refresh token.

Responses

200

application/json

token_typestringOptional

The token type.

access_tokenstringOptional

The access token.

refresh_tokenstringOptional

The refresh token.

expires_inintegerOptional

The access token expiration time in seconds.

4XX

Error

post/auth/refresh_token

POST /api/auth/refresh_token HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "refresh_token": null
}

{
  "token_type": "text",
  "access_token": "text",
  "refresh_token": "text",
  "expires_in": 1
}

Get the authentication information of the logged-in user.

get

Get the authentication information of the logged-in user.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

application/json

domainstring · min: 1 · max: 280Optional

role_idstringOptional

The unique ID of the resource.

Example: NzAwNTUxOTA5NzczMTQ4MTYw

role_namestring · min: 1 · max: 64Optional

Roles include built-in roles and custom roles.
Built-in roles roles cannot be modified.
Also, the names of built-in roles are reserved words,
custom roles are not allowed to use these names to avoid unnecessary confusion.
Built-in roles include:

SystemAdmin: the system administrator has almost all permissions.
OperationsAdmin: the operations administrator.
SiteAdmin: the site administrator.
Dealer: the sales manager has all sold tenant resource permissions.
Admin: the admin has all tenant-wide resource permissions.
StandardUser: the user all user-wide resource permissions.
StandardInternationalUser: the user all user-wide resource permissions with international call permissions.
QueueManager: The call queue manager.

Example: User

capabilitiesstring[]Optional

The permission string.

password_verifiedbooleanOptional

Whether the user password has been verified.

Example: true

password_force_resetbooleanOptional

Whether to force reset the initial password.

Default: false

401

Unauthorized

get/auth/user

GET /api/auth/user HTTP/1.1
Host: HOSTNAME:8887
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "domain": null,
  "role_id": null,
  "role_name": null,
  "capabilities": null,
  "password_verified": null,
  "password_force_reset": null
}

get

Get login status of current session.

Responses

200

application/json

access_tokenstringOptional

Access token to be passed as a header

Example: 4DFCF1D4C30B4D798ECE3AE43769F008.

expires_atstring · date_timeOptional

The expiration date of the access token in RFC 3339 format, for example, 2017-07-21T17:32:28Z. The RFC 3339 format is defined by RFC 3339, section 5.6

Example: 2017-07-21T17:32:28Z

expires_ininteger · int32Read-onlyOptional

The number of seconds that the access token will be valid.

Example: 1800

rolestring · min: 1 · max: 64Optional

SystemAdmin: the system administrator has almost all permissions.
OperationsAdmin: the operations administrator.
SiteAdmin: the site administrator.
Dealer: the sales manager has all sold tenant resource permissions.
Admin: the admin has all tenant-wide resource permissions.
StandardUser: the user all user-wide resource permissions.
StandardInternationalUser: the user all user-wide resource permissions with international call permissions.
QueueManager: The call queue manager.

Example: User

401

Unauthorized

get/login

GET /api/login HTTP/1.1
Host: HOSTNAME:8887
Accept: */*

{
  "access_token": null,
  "expires_at": null,
  "expires_in": null,
  "role": null
}

post

Body

usernamestring · min: 1 · max: 64Required

passwordstringRequired

The password of user.

domainstring · min: 1 · max: 280Optional

Responses

200

No content

4XX

Error

post/login

POST /api/login HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "username": null,
  "password": null,
  "domain": null
}

No content

post

Body

domainstring · min: 1 · max: 280Required

Responses

200

No content

302

Found

4XX

Error

post/login/by_microsoft

POST /api/login/by_microsoft HTTP/1.1
Host: HOSTNAME:8887
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 15

"domain=null"

No content

Log out from system

post

Logs out current session.

Responses

204

No Content

No content

4XX

Error

post/logout

POST /api/logout HTTP/1.1
Host: HOSTNAME:8887
Accept: */*

No content

PreviousUsers

NextTenants

Last updated 8 months ago

Was this helpful?

Retrieve metadata.

Sign in with credentials

Sign in with social account

Sign out from system.

Send OTP to email.

Verify OTP from email.

Initiate authentication forget password flow

Reset password with session token.

Refresh the access token.

Get the authentication information of the logged-in user.

Get login status of current session

Login into system

login with Microsoft Identity Provider by Authorization Code Flow

Log out from system