PhoneBurner OAuth authentication.
OAuth is a protocol that lets external apps request authorization to private details in a user's PhoneBurner account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.
All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.
The PhoneBurner OAuth server grants access to a user/vendor by issuing an
access_token. Like a locked door that can open in multiple ways - such as with a key or passcode - the
OAuth server can support multiple grant types to provide access.
This document will explain the flow of using OAuth from a 3rd party website.
This is a description of the OAuth2 flow from 3rd party web sites.
1. Redirect users to request PhoneBurner access
Used to obtain an authorization code. If the user has not already signed in, they will be redirected to /oauth/signin.
https://www.phoneburner.com/oauth/indexParameters
| Type | Description |
|---|---|
| client_id | Required. The client ID you received from PhoneBurner when you registered your app. |
| redirect_uri | Required. The redirect_uri must match the client provided endpoint. This parameter must be urlencoded. |
| response_type | Required. Must be code. |
| state | Optional. The state provides you a way to send data you need to get back. Examples are user identification, session id, or any other url encoded data. This same data will be sent back with the code to retrieve access tokens. |
| owner_type | Optional. If you are acting on behalf of a vendor account, then you must include and set to vendor. |
2. PhoneBurner redirects back to your site
If the user accepts your request, PhoneBurner redirects back to your site with a temporary code in a code parameter.
Exchange this code for an access token with the /oauth/accesstoken route.
POST https://www.phoneburner.com/oauth/accesstokenParameters:
| Type | Description |
|---|---|
| client_id | Required. The client ID you received from PhoneBurner when you registered. |
| client_secret | Required. The client secret you received from PhoneBurner when you registered. |
| code | Required. This was sent to you in the /oauth/index redirect. |
| redirect_uri | Required. Must be identical to the one used in the /oauth/index request. |
| grant_type | Required. Must be authorization_code. |
In this example POST, -X specfies the HTTP verb and -d specify data.
$ curl -X POST https://www.phoneburner.com/oauth/accesstoken \
-d "client_id=878518e02c5e4bbf38784a0644db99feabe55a89" \
-d "client_secret=6aff8f3bf1c273293c6536ed5e334609a5a0bf36" \
-d "redirect_uri=http://www.mywebsite.com/callback_route.php" \
-d "grant_type=authorization_code" \
-d "code=nELDUs1Qscz2Z4P82sXMFreCQQCagVNSq5Tt0KlW"
{
"access_token": "1lSalOdeDUL1Iq1L2Z6iIHfCZvjQmBXxKEGNZIOX",
"token_type": "bearer",
"expires": 1406411164,
"expires_in": 604800,
"refresh_token": "ejePMsN0rMBeFSJZXgEOvYmhLc4X0eDgjq7Q7ATB"
}
3. Use the access token to access the API
The access token allows you to make requests to the API on a behalf of a user.
$ curl -H 'Authorization: Bearer IJXYlIOkDEttK7cjk0lWyWHczRzWRCW1p60W5s1Z' https://www.phoneburner.com/[api_route]↑ Top
The PhoneBurner OAuth server supports the following grant types:
The OAuth server has four endpoints.
| HTTP Verb | Route | Description |
|---|---|---|
| GET | /oauth/authorize |
Used in the web application flow to authorize an OAuth client application |
| POST | /oauth/accesstoken |
Used in the web application flow to issue an access_token |
| POST | /oauth/refreshtoken |
Used in the refresh_token flow to get a new access_token |
| GET | /oauth/index |
Used in the web application flow to authenticate a user |
Used to obtain an authorization code. If the user/vendor has not signed in to authenticate, then they will be redirected to /oauth/signin.
| Type | Description |
|---|---|
| client_id | Required. The Client ID you received from PhoneBurner when you registered. |
| redirect_uri | Required. The redirect_uri must match the client provided endpoint. This parameter must be urlencoded. |
| response_type | Required. Must be code. |
| state | Optional. The state provides you a way to send data you need to get back. Examples are user identification, session id, or any other url encoded data. This same data will be sent back with the code to retrieve access tokens. |
| owner_type | Optional. If you are acting on behalf of a vendor account, then you must include and set to vendor. |
For an OAuth server authorization endpoint at https://www.phoneburner.com/oauth/authorize with
client_id 878518e02c5e4bbf38784a0644db99feabe55a89,
and redirect_uri https://www.yourdomain.com/callback_route2.php,
the corresponding browser link to start the web flow is:
https://www.phoneburner.com/oauth/authorize?client_id=878518e02c5e4bbf38784a0644db99feabe55a89&redirect_uri=http%3A%2F%2Fwww.yourdomain.com%2Fcallback_route2.php&response_type=code
If you are a vendor, then the start of the web flow would be:
https://www.phoneburner.com.com/oauth/authorize?client_id=878518e02c5e4bbf38784a0644db99feabe55a89&redirect_uri=http%3A%2F%2Fwww.yourdomain.com%2Fcallback_route2.php&response_type=code&owner_type=vendor
If the user/vendor has not yet authenticated, they will be redirected to /oauth/signin where they must provide their
username/password credentials or if they are a vendor, their access_key/secret_key credentials.
After authenticating, the user/vendor will be prompted with an authorization form asking their permission to let your app connect with their PhoneBurner account.
When the user clicks on the Approve button, they will be redirected to the provided redirect_uri
along with a code value.
Example: https://www.yourdomain.com/callback_route2.php?code=878518e02c5e4bbf38784a06
Note: The default client callback will automatically connect the issued code to a /oauth/accesstoken request.
The final step is to do a POST call to /oauth/accesstoken using this newly obtained code.
The /oauth/accesstoken endpoint exchanges the client credentials and the authorization code received from /oauth/authorize for an access_token.
| Type | Description |
|---|---|
| client_id | Required. The Client ID you received from PhoneBurner when you registered. |
| client_secret | Required*. The client secret you received from PhoneBurner when you registered. |
| code | Required. What was sent back in the authorize redirect. |
| redirect_uri | Required. Must be identical to the one used in the authorize request. |
| grant_type | Required. Must be authorization_code. |
* The client_secret is required but not verified in the version of the OAuth2 client we are currently using.
Note: The refresh token does expire but has a longer duration then the access_token.
A sample curl call:
using the newly acquired code from the /oauth/authorize step and the client_secret looks like:
$ curl -X POST https://www.phoneburner.com/oauth/accesstoken \
-d "client_id=878518e02c5e4bbf38784a0644db99feabe55a89" \
-d "client_secret=6aff8f3bf1c273293c6536ed5e334609a5a0bf36" \
-d "redirect_uri=http://www.yourdomain.com/callback_route2.php" \
-d "grant_type=authorization_code" \
-d "code=nELDUs1Qscz2Z4P82sXMFreCQQCagVNSq5Tt0KlW"
In the call, -X specfies the HTTP verb, -d specify data, and \
is used to show the command across multiple lines.
A sample response is:
{
"access_token": "1lSalOdeDUL1Iq1L2Z6iIHfCZvjQmBXxKEGNZIOX",
"token_type": "bearer",
"expires": 1406411164,
"expires_in": 604800,
"refresh_token": "ejePMsN0rMBeFSJZXgEOvYmhLc4X0eDgjq7Q7ATB"
}
Note: It is up to the client to securely store both the access_token and the refresh_token.
↑ TopThe /oauth/refreshtoken endpoint exchanges the client credentials and a refresh_token for a new access_token.
| Type | Description |
|---|---|
| client_id | Required. The Client ID you received from PhoneBurner when you registered. |
| client_secret | Required*. The Client Secret you received from PhoneBurner when you registered. |
| refresh_token | Required. The refresh token received in a previously successful /oauth/accesstoken response. |
| grant_type | Required. Must be refresh_token. |
* The client_secret is required but not verified in the version of the OAuth2 Client we are currently using.
A sample curl call to obtain a new access_token with a refresh_token is:
$ curl -X POST https://www.phoneburner.com/oauth/refreshtoken \
-d "client_id=878518e02c5e4bbf38784a0644db99feabe55a89" \
-d "client_secret=6aff8f3bf1c273293c6536ed5e334609a5a0bf36" \
-d "refresh_token=ejePMsN0rMBeFSJZXgEOvYmhLc4X0eDgjq7Q7ATB" \
-d "grant_type=refresh_token"
And the successful response:
{
"access_token": "IJXYlIOkDEttK7cjk0lWyWHczRzWRCW1p60W5s1Z",
"token_type": "bearer",
"expires": 1408487234,
"expires_in": 2678400
}
↑ Top
+--------+ +---------------+
| |--(A)---- Authorization ------------------>| |
| | /oauth/authorize OR | |
| | /oauth/signin then /oauth/authorize | |
| | | |
| Client |<-(B)----------- Code ---------------------| Authorization |
| | or error message | Server |
| |--(C)---- Access token request------------>| |
| | /oauth/accesstoken | |
| | | |
| |<-(D)----------- Access Token -------------| |
| | & Refresh Token | |
+--------+ or error message +---------------+
+--------+ +---------------+
| |--(A)---- Refresh token ------------------>| |
| | /oauth/refreshtoken | |
| | | |
| Client |<-(B)----------- Access Token -------------| Authorization |
| | or error message | Server |
| | | |
| | | |
+--------+ +---------------+
↑ Top Accessing resources with the OAuth token follows this basic flow:
+--------+ +----------+ | |--(A)---- API Request with -->| | | | Access Token in | | | | Authorization Header | Resource | | Client | | Server | | |<-- (B) Protected Resource ---| | | | or error message | | | | | | | | | | +--------+ +----------+
To use the API, include the access_token in an Authorization header:
Authorization: Bearer [YOUR-OAUTH-ACCESS-TOKEN]
An example using curl, where -H specifies a header:
$ curl https://www.phoneburner.com/rest/1/[route] -H 'Authorization: Bearer IJXYlIOkDEttK7cjk0lWyWHczRzWRCW1p60W5s1Z'
Please refer to API usage examples.
↑ TopHere are some common error responses.
A missing or invalid parameter value. The offending parameter is specified, such as the response below which says to check the client_id.
{
"error": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"client_id\" parameter."
}
The user/vendor denied authorization to the client.
{
"error": "access_denied",
"error_message": "The resource owner or authorization server denied the request."
}
The error response might also be in the callback URL query string. For example:
https://www.yourdomain.com/default_oauth_callback.php?error=access_denied&error_message=The%20resource%20owner%20or%20authorization%20server%20denied%20the%20request.
Invalid/unknown client_id
{
"error": "invalid client_id",
"error_message": "invalid client_id: 878x518e02c5e4bbf38784a0644db99feabe55a89"
}
During the /oauth/accesstoken call you may recieve this error which can be caused by a client_id, redirect_uri or grant_type that does not align with the issued code or a code that has already been
used for an access_token. It can also occur if you are using an invalid code.
{
"error": "invalid_grant",
"error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. Check the \"code\" parameter."
}