# Authentication
Manage authentication.
## Retrieve metadata.
> 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\` \
> Tenant metadata: \
> \- \`name\`\
> \- \`domain\`\
> \- \`website\`\
> \- \`avatar\_url\`\
> \- \`enable\_ms365\_integration\`\
> \- \`ms365\_authorization\_endpoint\`
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/info":{"get":{"tags":["Authentication"],"operationId":"retrieveMetadata","summary":"Retrieve metadata.","description":"Retrieve system metadata information. \nIf the optional `domain` query parameter is specified, \nthe relevant tenant metadata information will be returned together. \nSystem metadata: \n- `web_domain`\n- `private_ipv4`\n- `public_ipv4`\n- `enable_ipv6`\n- `private_ipv6`\n- `public_ipv6`\n- `primary_dns_server`\n- `secondary_dns_server` \nTenant metadata: \n- `name`\n- `domain`\n- `website`\n- `avatar_url`\n- `enable_ms365_integration`\n- `ms365_authorization_endpoint`\n","parameters":[{"name":"domain","in":"query","schema":{"type":"string"},"description":"Use the `domain` query parameter to retrieve just a subset of a collection.\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"web_domain":{"type":"string","description":"The web domain for PortSIP PBX\n"},"private_ipv4":{"type":"string","description":"The private IPv4 of system.\n"},"public_ipv4":{"type":"string","description":"The public IPv4 of system.\n"},"enable_ipv6":{"type":"boolean","default":true,"description":"Indicates if IPv6 would be enabled.\n"},"private_ipv6":{"type":"string","description":"The private IPv6 of system.\n"},"public_ipv6":{"type":"string","description":"The public IPv6 of system.\n"},"primary_dns_server":{"type":"string","description":"The primary DNS server.\n"},"secondary_dns_server":{"type":"string","description":"The secondary DNS server.\n"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"The name of the tenant.\n"},"domain":{"type":"string","minLength":1,"maxLength":280,"description":"The SIP domain of tenant. \nIt is usually a fully qualified domain name (FQDN).\nIf there is no FQDN, you can also use the IP address of the PBX server as the SIP domain.\nThe SIP domain name is only used for SIP message authentication and does not require analysis.\n"},"website":{"type":"string","maxLength":255,"description":"The official website of tenant.\n"},"avatar_url":{"type":"string","readOnly":true,"description":"The relative path to file url for file downloading.\n"},"enable_ms365_integration":{"type":"boolean","description":"Microsoft 365 SSO integration enabled or not.\n"},"ms365_authorization_endpoint":{"type":"string","description":"The Microsoft Identity Provider authorization endpoint for this tenant.\n"}}}}}},"4XX":{"description":"Error"}}}}}}
```
## Sign in with credentials
> Sign in with credentials
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/sign_in":{"post":{"tags":["Authentication"],"operationId":"signInWithCredentials","summary":"Sign in with credentials","description":"Sign in with credentials\n","parameters":[{"name":"qr","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","minLength":1,"maxLength":64,"description":"The user's account name. \nOnly letters, numbers, and the following special characters can be added: underscore, dash, single quote, and period (_, -, ', and .). \nUsername cannot start or end with period (.). \n`admin`, `system`, `administrator`, and `root` are reserved names for system admin only with case ignored.\n"},"password":{"type":"string","description":"The password of user.\n"},"domain":{"type":"string","minLength":1,"maxLength":280,"description":"The SIP domain of tenant. \nIt is usually a fully qualified domain name (FQDN).\nIf there is no FQDN, you can also use the IP address of the PBX server as the SIP domain.\nThe SIP domain name is only used for SIP message authentication and does not require analysis.\n"}},"required":["username","password"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"two_factor_enabled":{"type":"boolean","description":"Indicates that two factor authentication is enabled. Always true.\n"},"token":{"type":"string","description":"The session token in authentication flow.\n"}}},{"type":"object","properties":{"token_type":{"type":"string","description":"The token type.\n"},"access_token":{"type":"string","description":"The access token.\n"},"refresh_token":{"type":"string","description":"The refresh token.\n"},"expires_in":{"type":"integer","description":"The access token expiration time in seconds."}}}]}}}},"4XX":{"description":"Error"}}}}}}
```
## Sign in with social account
> Sign in with social account
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/sign_in/{provider}":{"post":{"tags":["Authentication"],"operationId":"signInWithSocialAccount","summary":"Sign in with social account","description":"Sign in with social account\n","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"The name of IdP provider. Currently only supports microsoft.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":280,"description":"The SIP domain of tenant. \nIt is usually a fully qualified domain name (FQDN).\nIf there is no FQDN, you can also use the IP address of the PBX server as the SIP domain.\nThe SIP domain name is only used for SIP message authentication and does not require analysis.\n"},"callback_url":{"type":"string","description":"The callback url for authentication flow.\n"}},"required":["domain","callback_url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The IdP authentication url.\n"}}}}}},"4XX":{"description":"Error"}}}}}}
```
## Sign out from system.
> Sign out from system.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/auth/sign_out":{"post":{"tags":["Authentication"],"operationId":"signOut","summary":"Sign out from system.","description":"Sign out from system.\n","responses":{"200":{"description":"OK"},"4XX":{"description":"Error"}}}}}}
```
## Send OTP to email.
> Request to send OTP to email.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/send_otp":{"post":{"tags":["Authentication"],"operationId":"sendOTP","summary":"Send OTP to email.","description":"Request to send OTP to email.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The session token in authentication flow.\n"}},"required":["token"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"description":"Error"}}}}}}
```
## Verify OTP from email.
> Request to verify OTP from email.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/verify_otp":{"post":{"tags":["Authentication"],"operationId":"verifyOTP","summary":"Verify OTP from email.","description":"Request to verify OTP from email.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The session token in authentication flow.\n"},"code":{"type":"string","description":"The OTP code in authentication flow.\n"}},"required":["token","code"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"description":"Error"}}}}}}
```
## Initiate authentication forget password flow
> Initiate authentication forget password flow.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/forget_password":{"post":{"tags":["Authentication"],"operationId":"forgetPassword","summary":"Initiate authentication forget password flow","description":"Initiate authentication forget password flow.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":280,"description":"The SIP domain of tenant. \nIt is usually a fully qualified domain name (FQDN).\nIf there is no FQDN, you can also use the IP address of the PBX server as the SIP domain.\nThe SIP domain name is only used for SIP message authentication and does not require analysis.\n"},"username":{"type":"string","minLength":1,"maxLength":64,"description":"The user's account name. \nOnly letters, numbers, and the following special characters can be added: underscore, dash, single quote, and period (_, -, ', and .). \nUsername cannot start or end with period (.). \n`admin`, `system`, `administrator`, and `root` are reserved names for system admin only with case ignored.\n"},"callback_url":{"type":"string","description":"The callback url for authentication flow.\n"}},"required":["domain","username","callback_url"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"description":"Error"}}}}}}
```
## Reset password with session token.
> Reset password with session token.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/reset_password":{"post":{"tags":["Authentication"],"operationId":"resetPassword","summary":"Reset password with session token.","description":"Reset password with session token.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The session token in authentication flow.\n"},"new_password":{"type":"string","description":"The password of user.\n"}},"required":["token","new_password"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"description":"Error"}}}}}}
```
## Refresh the access token.
> Refresh the access token.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/auth/refresh_token":{"post":{"tags":["Authentication"],"operationId":"refreshToken","summary":"Refresh the access token.","description":"Refresh the access token.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","description":"The refresh token.\n"}},"required":["refresh_token"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"token_type":{"type":"string","description":"The token type.\n"},"access_token":{"type":"string","description":"The access token.\n"},"refresh_token":{"type":"string","description":"The refresh token.\n"},"expires_in":{"type":"integer","description":"The access token expiration time in seconds."}}}}}},"4XX":{"description":"Error"}}}}}}
```
## Get the authentication information of the logged-in user.
> Get the authentication information of the logged-in user.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/auth/user":{"get":{"tags":["Authentication"],"operationId":"getUserAuthInfo","summary":"Get the authentication information of the logged-in user.","description":"Get the authentication information of the logged-in user.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","minLength":1,"maxLength":64,"description":"Roles include built-in roles and custom roles. \nBuilt-in roles roles cannot be modified. \nAlso, the names of built-in roles are reserved words, \ncustom roles are not allowed to use these names to avoid unnecessary confusion. \nBuilt-in roles include: \n- `SystemAdmin`: the system administrator has almost all permissions.\n- `Replicator`: the application permissions collection.\n- `Dealer`: the sales manager has all sold tenant resource permissions\n- `Admin`: the admin has all tenant-wide resource permissions.\n- `StandardUser`: the user all user-wide resource permissions.\n- `StandardInternationalUser`: the user all user-wide resource permissions with international call permissions.\n- `QueueManager`: The call queue manager.\n"},"password_verified":{"type":"boolean","description":"Whether the user password has been verified.\n"},"password_force_reset":{"type":"boolean","default":false,"description":"Whether to force reset the initial password.\n"}}}}}},"401":{"description":"Unauthorized"}}}}}}
```
## Get login status of current session
> Get login status of current session.
````json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/login":{"get":{"tags":["Authentication"],"operationId":"getLoginStatus","summary":"Get login status of current session","description":"Get login status of current session.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"Access token to be passed as a header\n"},"expires_at":{"type":"string","format":"date_time","description":"The expiration date of the access token in RFC 3339 format, for example, ```2017-07-21T17:32:28Z```.\nThe RFC 3339 format is defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)\n"},"expires_in":{"type":"integer","format":"int32","readOnly":true,"description":"The number of seconds that the access token will be valid.\n"},"role":{"type":"string","minLength":1,"maxLength":64,"description":"Roles include built-in roles and custom roles. \nBuilt-in roles roles cannot be modified. \nAlso, the names of built-in roles are reserved words, \ncustom roles are not allowed to use these names to avoid unnecessary confusion. \nBuilt-in roles include: \n- `SystemAdmin`: the system administrator has almost all permissions.\n- `Replicator`: the application permissions collection.\n- `Dealer`: the sales manager has all sold tenant resource permissions\n- `Admin`: the admin has all tenant-wide resource permissions.\n- `StandardUser`: the user all user-wide resource permissions.\n- `StandardInternationalUser`: the user all user-wide resource permissions with international call permissions.\n- `QueueManager`: The call queue manager.\n"}}}}}},"401":{"description":"Unauthorized"}}}}}}
````
## Login into system
> Login with username and password.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/login":{"post":{"tags":["Authentication"],"operationId":"login","summary":"Login into system","description":"Login with username and password.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","minLength":1,"maxLength":64,"description":"The user's account name. \nOnly letters, numbers, and the following special characters can be added: underscore, dash, single quote, and period (_, -, ', and .). \nUsername cannot start or end with period (.). \n`admin`, `system`, `administrator`, and `root` are reserved names for system admin only with case ignored.\n"},"password":{"type":"string","description":"The password of user.\n"},"domain":{"type":"string","minLength":1,"maxLength":280,"description":"The SIP domain of tenant. \nIt is usually a fully qualified domain name (FQDN).\nIf there is no FQDN, you can also use the IP address of the PBX server as the SIP domain.\nThe SIP domain name is only used for SIP message authentication and does not require analysis.\n"}},"required":["username","password"]}}}},"responses":{"200":{"description":"OK"},"4XX":{"description":"Error"}}}}}}
```
## login with Microsoft Identity Provider by Authorization Code Flow
> login with Microsoft Identity Provider by Authorization Code Flow.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/login/by_microsoft":{"post":{"tags":["Authentication"],"operationId":"loginWithMicrosoft","summary":"login with Microsoft Identity Provider by Authorization Code Flow","description":"login with Microsoft Identity Provider by Authorization Code Flow.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":280,"description":"The SIP domain of tenant. \nIt is usually a fully qualified domain name (FQDN).\nIf there is no FQDN, you can also use the IP address of the PBX server as the SIP domain.\nThe SIP domain name is only used for SIP message authentication and does not require analysis.\n"}},"required":["domain"]}}}},"responses":{"302":{"description":"Found"},"4XX":{"description":"Error"}}}}}}
```
## Log out from system
> Logs out current session.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.0"},"tags":[{"name":"Authentication","description":"Manage authentication.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[],"paths":{"/logout":{"post":{"tags":["Authentication"],"operationId":"logout","summary":"Log out from system","description":"Logs out current session.\n","responses":{"204":{"description":"No Content"},"4XX":{"description":"Error"}}}}}}
```