{"_id":"58fd14a0cff73f1b00c5defd","__v":0,"category":{"_id":"58fd1460809fc30f00f2ee07","__v":0,"project":"55c8cff571d7580d0063a5e5","version":"57624356653c2d2200fec79c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-04-23T20:53:52.828Z","from_sync":false,"order":2,"slug":"oauth","title":"OAuth"},"user":"56f99ab84d2b4f3400edb636","version":{"_id":"57624356653c2d2200fec79c","__v":20,"project":"55c8cff571d7580d0063a5e5","createdAt":"2016-06-16T06:12:38.244Z","releaseDate":"2016-06-16T06:12:38.244Z","categories":["57624356653c2d2200fec79d","57624356653c2d2200fec79e","57624356653c2d2200fec79f","57624356653c2d2200fec7a0","57624356653c2d2200fec7a1","57624356653c2d2200fec7a2","57624356653c2d2200fec7a3","57624356653c2d2200fec7a4","57624356653c2d2200fec7a5","57624356653c2d2200fec7a6","57624356653c2d2200fec7a7","57624356653c2d2200fec7a8","57624356653c2d2200fec7a9","57624356653c2d2200fec7aa","5779ca1b99b40b0e005abb3a","5779d198aea88b0e00f63277","5797d3ab17ced017003c4be4","57ac170ef1cdae0e0053cdfc","57dbfc723ed3450e00dc9e6d","5804d12d16161c0f0077df9b","5841064b652e5b0f0015a7c8","588b5e5f2966b2230009cbf9","58a68ebf3239fa0f00857619","58c23c8b4922930f0050ac91","58fd1460809fc30f00f2ee07","5934eaf5328680002d77de6a","594bf91601cfe6000f40f4c5","595c4ed696b447001ba0cf6d","596524495cee50001575f5be","5970d4f1313162004dd303b5","59780fac24dbd1001a1fa057","59a8cfd3ead78a002d63cafe","59e0323d93da1f001c9ec170"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"4.0.0","version":"4"},"project":"55c8cff571d7580d0063a5e5","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-23T20:54:56.124Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"## Supported Services\n* [Create Authorization](doc:create-oauth-authorization)\n* [Create Access Token](doc:create-oauth-access-token)\n* [Get Access Token](doc:get-oauth-access-token)\n\n## Supported Grants\n\nFor security reason, an API application (OAuth client) needs to create an access token to make requests via the Phoenix API.  The Phone.com API implements the [OAuth 2.0](https://tools.ietf.org/html/rfc6749) standard and is basically an OAuth Authorization server. Every API application must first be registered as an OAuth Client and every such client is permitted to use certain OAuth grants. The Phone.com API provides five different types of grants for an OAuth client to create access tokens, some of them may be configured to expire within a specified TTL (time to live).\n\n- Authorization Code Grant: API user uses the client id and a pre-registered redirect_uri to create an authorization code, then uses the code, client id, and client secret to generate an access token and a refresh token.  An application wishing to gain access to some Phone.com user account can use this method to open a web browser where that user can authenticate and approve access to their account by that application, after which the browser will redirect to a pre-registered URI provided by the client in advance. That redirect URI will receive an authorization code as a query string parameter and that authorization code can be used by a server to get an access token using the client id and client secret.\n\n- Implicit Grant: This is a client side version of the Authorization Code Grant where the access token is returned instead of an authorization code making the last step above unnecessary. This method is allowed only in browsers, the access token is returned in the hash fragment of the redirect URI and since hash fragments are not part of an HTTP(s) request only the browser sees the token and hence HTTPS is not required for the redirect URI. Client side code in the browser must be used to store the token (passing it to a server is of-course possible but for security reasons requires HTTPS).\n\n- Client Credential Grant:  User provides client id, client secret and scope to create an access token.  The use case for this grant should be server to server interaction over HTTPS.\n\n- Password Credential Grant :  User provides client id, client secret, username and password to create an access token and a refresh token.  The use case for this grant is Phone.com owned applications only and is not intended for API users because the user credentials are exposed to the application.\n\n- Refresh Token Grant:  The refresh token grant is designed to refresh an expired access token and can be used along with any of the above grants when the token expires.\n\nThe OAuth client id and client secret are provided by Phone.com on a need by need basis.  Phone.com customers can request an OAuth client id and secret for their application, by emailing apisupport:::at:::phone.com or contact [Customer Support](http://support.phone.com).\n\n## Response Object for Authorization response_type=token\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"URL\",\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The redirected URI\",\n    \"1-0\": \"Token Type\",\n    \"1-1\": \"String\",\n    \"1-2\": \"Bearer\",\n    \"2-0\": \"Expire Time\",\n    \"2-1\": \"Integer\",\n    \"2-2\": \"TTL in seconds, after this length of time, the token expires and becomes invalid\",\n    \"3-0\": \"Access Token\",\n    \"3-1\": \"String\",\n    \"3-2\": \"The newly created Access Token\",\n    \"4-0\": \"State\",\n    \"4-1\": \"String\",\n    \"4-2\": \"An opaque value used by the client to maintain state between the request and callback.  The value of state is provided as input, and is returned in the response.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://localhost/#token_type=Bearer&expires_in=3600&access_token=c1VhLHk76RM222APPQzhyYNUmJh89BZDyQ706656~6&state=abc\",\n      \"language\": \"http\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n## Response Object for Authorization response_type=code\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"URL\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The redirected URI\",\n    \"1-0\": \"Code\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The newly created Authorization Code\",\n    \"2-0\": \"State\",\n    \"2-1\": \"String\",\n    \"2-2\": \"An opaque value used by the client to maintain state between the request and callback\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://localhost/?code=mRxUuwgl0Xgjg8fIjweikoJPb1ffMBU8bt706656~6&state=xyz\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n## Response Object for Access Token\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"access_token\",\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Access Token used to execute http request\",\n    \"1-0\": \"token_type\",\n    \"1-1\": \"String\",\n    \"1-2\": \"Bearer\",\n    \"2-0\": \"scope\",\n    \"2-1\": \"String\",\n    \"2-2\": \"Account-owner: token can be used to perform account level API\\n\\nExtension-user: token can be used to perform extension level API, such as contacts and groups\",\n    \"3-0\": \"refresh_token\",\n    \"3-2\": \"Token can be used to request a new access token when the old one expired\",\n    \"4-0\": \"expires_in\",\n    \"4-1\": \"Integer\",\n    \"3-1\": \"String\",\n    \"4-2\": \"The time in seconds when the access token expires and becomes invalid\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n## Glossary\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Account\",\n    \"1-0\": \"Access Token\",\n    \"2-0\": \"Authorization Code\",\n    \"3-0\": \"Client\",\n    \"4-0\": \"Refresh Token\",\n    \"5-0\": \"Resource Owner\",\n    \"6-0\": \"Scope\",\n    \"3-1\": \"Client is a phone.com component tasked with making protected and authorized requests to internal protected resources.\",\n    \"5-1\": \"Person who owns the Phone.com account\",\n    \"0-1\": \"Phone.com account is a Resource represented by VoiP ID. To get access to an account via the Phone.com API one will require an Access Token.\",\n    \"1-1\": \"Access tokens are credentials used to access protected resources such as your Phone.com account. The access token is a string representing an authorization issued to the Client.  Tokens represent specific scopes and durations of access, granted by the resource owner and enforced by Phone.com.\",\n    \"2-1\": \"Authorization Code is an intermediary code between the Client and Resource owner.  Instead of requesting authorization directly from the resource owner, the Client directs the resource owner to an authorization page which will direct the server to send the Client the authorization code to a URL provided by the requesting page.\",\n    \"4-1\": \"Refresh Tokens are credentials used to obtain Access Tokens.  Refresh tokens are issued to an authorized requester asking to obtain new access token when the current Access Token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).  \\n\\nWhen the authorization endpoint returns the access token, It usually returns a fresh token as well.\",\n    \"6-1\": \"The OAuth API allows the client to specify the Scope of the access request using the \\\"scope\\\" request parameter.  In turn, the authorization process uses the \\\"scope\\\" response parameter to inform the client of the scope of the access token issued.  The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. The order does not matter, and each string adds an additional access range to the requested scope.\\n\\nScope 'account-owner' allows access token to execute account level API; Scope 'extension-user' allows access token to execute extension level API.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]","excerpt":"The [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) enables a third-party application to obtain limited access to HTTP API requests which require an access token.  This page describes how to use the /oauth/authorization and /oauth/access-token API's to generate an access token.","slug":"oauth","type":"basic","title":"OAuth"}

OAuth

The [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) enables a third-party application to obtain limited access to HTTP API requests which require an access token. This page describes how to use the /oauth/authorization and /oauth/access-token API's to generate an access token.

## Supported Services * [Create Authorization](doc:create-oauth-authorization) * [Create Access Token](doc:create-oauth-access-token) * [Get Access Token](doc:get-oauth-access-token) ## Supported Grants For security reason, an API application (OAuth client) needs to create an access token to make requests via the Phoenix API. The Phone.com API implements the [OAuth 2.0](https://tools.ietf.org/html/rfc6749) standard and is basically an OAuth Authorization server. Every API application must first be registered as an OAuth Client and every such client is permitted to use certain OAuth grants. The Phone.com API provides five different types of grants for an OAuth client to create access tokens, some of them may be configured to expire within a specified TTL (time to live). - Authorization Code Grant: API user uses the client id and a pre-registered redirect_uri to create an authorization code, then uses the code, client id, and client secret to generate an access token and a refresh token. An application wishing to gain access to some Phone.com user account can use this method to open a web browser where that user can authenticate and approve access to their account by that application, after which the browser will redirect to a pre-registered URI provided by the client in advance. That redirect URI will receive an authorization code as a query string parameter and that authorization code can be used by a server to get an access token using the client id and client secret. - Implicit Grant: This is a client side version of the Authorization Code Grant where the access token is returned instead of an authorization code making the last step above unnecessary. This method is allowed only in browsers, the access token is returned in the hash fragment of the redirect URI and since hash fragments are not part of an HTTP(s) request only the browser sees the token and hence HTTPS is not required for the redirect URI. Client side code in the browser must be used to store the token (passing it to a server is of-course possible but for security reasons requires HTTPS). - Client Credential Grant: User provides client id, client secret and scope to create an access token. The use case for this grant should be server to server interaction over HTTPS. - Password Credential Grant : User provides client id, client secret, username and password to create an access token and a refresh token. The use case for this grant is Phone.com owned applications only and is not intended for API users because the user credentials are exposed to the application. - Refresh Token Grant: The refresh token grant is designed to refresh an expired access token and can be used along with any of the above grants when the token expires. The OAuth client id and client secret are provided by Phone.com on a need by need basis. Phone.com customers can request an OAuth client id and secret for their application, by emailing apisupport@phone.com or contact [Customer Support](http://support.phone.com). ## Response Object for Authorization response_type=token [block:parameters] { "data": { "0-0": "URL", "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-1": "String", "0-2": "The redirected URI", "1-0": "Token Type", "1-1": "String", "1-2": "Bearer", "2-0": "Expire Time", "2-1": "Integer", "2-2": "TTL in seconds, after this length of time, the token expires and becomes invalid", "3-0": "Access Token", "3-1": "String", "3-2": "The newly created Access Token", "4-0": "State", "4-1": "String", "4-2": "An opaque value used by the client to maintain state between the request and callback. The value of state is provided as input, and is returned in the response." }, "cols": 3, "rows": 5 } [/block] Here is an example: [block:code] { "codes": [ { "code": "http://localhost/#token_type=Bearer&expires_in=3600&access_token=c1VhLHk76RM222APPQzhyYNUmJh89BZDyQ706656~6&state=abc", "language": "http", "name": null } ] } [/block] ## Response Object for Authorization response_type=code [block:parameters] { "data": { "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-0": "URL", "0-1": "String", "0-2": "The redirected URI", "1-0": "Code", "1-1": "String", "1-2": "The newly created Authorization Code", "2-0": "State", "2-1": "String", "2-2": "An opaque value used by the client to maintain state between the request and callback" }, "cols": 3, "rows": 3 } [/block] Here is an example: [block:code] { "codes": [ { "code": "http://localhost/?code=mRxUuwgl0Xgjg8fIjweikoJPb1ffMBU8bt706656~6&state=xyz", "language": "http" } ] } [/block] ## Response Object for Access Token [block:parameters] { "data": { "0-0": "access_token", "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-1": "String", "0-2": "Access Token used to execute http request", "1-0": "token_type", "1-1": "String", "1-2": "Bearer", "2-0": "scope", "2-1": "String", "2-2": "Account-owner: token can be used to perform account level API\n\nExtension-user: token can be used to perform extension level API, such as contacts and groups", "3-0": "refresh_token", "3-2": "Token can be used to request a new access token when the old one expired", "4-0": "expires_in", "4-1": "Integer", "3-1": "String", "4-2": "The time in seconds when the access token expires and becomes invalid" }, "cols": 3, "rows": 5 } [/block] ## Glossary [block:parameters] { "data": { "0-0": "Account", "1-0": "Access Token", "2-0": "Authorization Code", "3-0": "Client", "4-0": "Refresh Token", "5-0": "Resource Owner", "6-0": "Scope", "3-1": "Client is a phone.com component tasked with making protected and authorized requests to internal protected resources.", "5-1": "Person who owns the Phone.com account", "0-1": "Phone.com account is a Resource represented by VoiP ID. To get access to an account via the Phone.com API one will require an Access Token.", "1-1": "Access tokens are credentials used to access protected resources such as your Phone.com account. The access token is a string representing an authorization issued to the Client. Tokens represent specific scopes and durations of access, granted by the resource owner and enforced by Phone.com.", "2-1": "Authorization Code is an intermediary code between the Client and Resource owner. Instead of requesting authorization directly from the resource owner, the Client directs the resource owner to an authorization page which will direct the server to send the Client the authorization code to a URL provided by the requesting page.", "4-1": "Refresh Tokens are credentials used to obtain Access Tokens. Refresh tokens are issued to an authorized requester asking to obtain new access token when the current Access Token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner). \n\nWhen the authorization endpoint returns the access token, It usually returns a fresh token as well.", "6-1": "The OAuth API allows the client to specify the Scope of the access request using the \"scope\" request parameter. In turn, the authorization process uses the \"scope\" response parameter to inform the client of the scope of the access token issued. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. The order does not matter, and each string adds an additional access range to the requested scope.\n\nScope 'account-owner' allows access token to execute account level API; Scope 'extension-user' allows access token to execute extension level API." }, "cols": 2, "rows": 7 } [/block]