Authorization Code Grant

The OAuth 2.0 Authorization Code Grant can be used to authenticate clients of this API and then gain an Access Token and Refresh Token.

For this to work you must first have your redirect URI whitelisted and you must have a valid Client ID and Client Secret. To get a Client ID and Secret please open a support ticket here.

Authorization Request

The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the application/x-www-form-urlencoded format, per RFC 6749 Appendix B:

`response_type` #REQUIRED  Value MUST be set to "code".
`client_id` #REQUIRED  The client id.
`redirect_uri` #REQUIRED  As described in Section [3.1.2](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2).
`state` #REQUIRED

Example:

# Split by lines for readability
GET /portal/?
	response_type=code
	&redirect_uri=<myUrlEncodedRedirect.com> 
	&state=<myState>
	&client_id=<myClientId>
host myonecloud.com

Authorization Response

The above request will take the user to the OneCloud UCaaS login page where they can input their username and password. The system will then grant an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format, per RFC 6749 Appendix B:

`code` #REQUIRED The authorization code generated by the authorization server.
`state` #REQUIRED The state sent in the original Authorization request.

For example, the authorization server redirects the user-agent by sending the following HTTP response:

 HTTP/1.1 302 Found
 Location: https://<myUrlEncodedRedirect.com>/cb?code=SplxlOBeZQQYbYS6WxSbIA
           &state=xyz

Access Token Request

You must now exchange the code received for an Access Token by sending the following parameters using the application/x-www-form-urlencoded format per Appendix B with a character encoding of UTF-8 in the HTTP request entity-body. You must also send the Client ID and Client Secret as Basic Authorization

grant_type REQUIRED.  Value MUST be set to "authorization_code".    
code REQUIRED.  The authorization code received from the authorization server.
redirect_uri REQUIRED, the "redirect_uri" parameter should match the redirect_uri included in the authorization request as described in Section 4.1.1 of RFC 6749.
client_id REQUIRED, if the client is not authenticating with the authorization server as described in Section 3.2.1 of RFC 6749.

For Example

curl --location 'https://myonecloud.com/ns-api/oauth2/token/?code=9b1a04974b540ff8826ee8c78c2e1fef&redirect_uri=https%3A%2F%2Fdev.onecloud.com%2Fredirect&grant_type=authorization_code' \
--header 'Authorization: Basic clientId and ClientSecret'

{
    "client_id": "testing",
    "territory": "Demo",
    "domain": "onecloud",
    "uid": "1001@onecloud",
    "expires": "1710591582",
    "scope": "Office Manager",
    "token_type": "Bearer",
    "rate_limit": "0",
    "login": "1001@onecloud",
    "user_email": "[email protected]",
    "displayName": "Development One",
    "access_token": "F3222DAB27BE448D6DFC72D3824973",
    "expires_in": 3600,
    "refresh_token": "7566A32E97E4D579B882E63637BA4B",
    "apiversion": "Version: 44.1.0"
}

User Profile

Now that you have been granted an Access Token you can use it to pull the user's profile. See Get My User. Keep in mind that your Access Token will expire after 1 hour so you will need to use your refresh token to get a new Access Token. See Get Access Token From Refresh. When requesting a new access token you will receive a new refresh token as well to use for next call.

curl --location 'https://myonecloud.com/ns-api/v2/domains/~/users/~' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access_token>'

{
    "domain": "onecloud",
    "user": "1001",
    "name-first-name": "Development",
    "name-last-name": "One",
    "login-username": "1001@onecloud",
    "user-scope": "Office Manager",
    "department": "Tech",
    "site": "main",
    "user-presence-status": "inactive",
    "time-zone": "US/Eastern",
    "area-code": 704,
    "caller-id-number": 7045984700,
    "caller-id-name": "OneCloud",
    "dial-plan": "onecloud",
    "dial-policy": "Purple Plan",
    "account-status": "standard",
    "active-calls-total-current": 0,
    "call-recordings-hide-from-others-enabled": "no",
    "call-screening-enabled": "yes",
    "caller-id-number-emergency": 8009219680,
    "created-datetime": "2/15/2019 19:51",
    "directory-annouce-in-dial-by-name-enabled": "no",
    "directory-name-number-dtmf-mapping": 762,
    "directory-name-visible-in-list-enabled": "yes",
    "directory-override-order-duplicate-dtmf-mapping": 1,
    "email": "[email protected]",
    "email-send-alert-data-storage-limit-reached-enabled": "",
    "email-send-alert-new-missed-call-enabled": "",
    "email-send-alert-new-voicemail-behavior": "yesnew",
    "email-send-alert-new-voicemail-cc-list-csv": "",
    "email-send-alert-new-voicemail-enabled": "yes",
    "emergency-address-id": "a-6128245f493f1",
    "language-token": "en_us",
    "last-modified-datetime": "2024-03-08T14:55:45+00:00",
    "limits-max-active-calls-total": 0,
    "limits-max-data-storage-kilobytes": 10000,
    "mfa": [
        {
            "mfa_vendor": "google",
            "mfa_type": "authenticator"
        }
    ],
    "music-on-hold-comfort-message-repeat-interval-seconds": 30,
    "music-on-hold-randomized-enabled": "no",
    "phone-numbers-to-allow-enabled": "yes",
    "phone-numbers-to-reject-enabled": "yes",
    "privacy": "no",
    "recording-configuration": "yes-with-transcription-and-sentiment",
    "reject-anonymous-calls-enabled": "no",
    "ring-no-answer-timeout-seconds": 25,
    "service-code": "",
    "sso_ids": [
    ],
    "status-message": "",
    "voicemail-enabled": "yes",
    "voicemail-greeting-index": 1,
    "voicemail-login-pin": 7705,
    "voicemail-playback-announce-caller-id": "no",
    "voicemail-playback-announce-date-time-received": "no",
    "voicemail-playback-sort-newest-to-oldest": "no",
    "voicemail-receive-broadcast-enabled": "",
    "voicemail-user-control-enabled": "yes"
}