Difference between revisions of "Application OAuth Token Generation"

From Active911 Documentation Wiki
Jump to: navigation, search
(Authorization Code)
Line 19: Line 19:
 
3rd party applications must use the Authorization Code workflow, starting with a request to https://access.active911.com/open_api/authorize_agency.php by using a GET request.
 
3rd party applications must use the Authorization Code workflow, starting with a request to https://access.active911.com/open_api/authorize_agency.php by using a GET request.
  
<table>
+
{|
<tr><th>Parameter</th><th>Required</th><th>Description</th></tr>
+
|Parameter
<tr><td>client_id</td><td>yes</td><td>The client_id given to your application when you registered it with us</td></tr>
+
|Required
<tr><td>response_type</td><td>yes</td><td>Currently we only support the Authorization Code workflow, so this must be set to "code"</td></tr>
+
|Description
<tr><td>redirection_uri</td><td>yes</td><td>The url you want the user to be redirected to after they authorize your request</td></tr>
+
|-
<tr><td>scope</td><td>yes</td><td>The permissions you are requesting access for</td></tr>
+
|client_id
<tr><td>state</td><td>no</td><td>You may set this to a particular value, and that value will be resent upon redirection after authorization</td></tr>
+
|yes
</table>
+
|The client_id given to your application when you registered it with us
 +
|-
 +
|client_secret
 +
|yes
 +
|The client_secret given to your application when you registered it with us
 +
|-
 +
|response_type
 +
|yes
 +
|Currently we only support the Authorization Code workflow, so this must be set to "code"
 +
|-
 +
|redirection_uri
 +
|yes
 +
|The url you want the user to be redirected to after they authorize your request
 +
|-
 +
|scope
 +
|yes
 +
|The permissions you are requesting access for
 +
|-
 +
|state
 +
|no
 +
|You may set this to a particular value, and that value will be resent upon redirection after authorization
 +
|}
  
 
Upon authorization by the user, this will redirect to the redirection uri specified with the authorization code included as a query parameter:
 
Upon authorization by the user, this will redirect to the redirection uri specified with the authorization code included as a query parameter:
Line 34: Line 55:
 
You may exchange the authorization code for an access token and refresh token at https://access.active911.com/open_api/token.php by using a POST request
 
You may exchange the authorization code for an access token and refresh token at https://access.active911.com/open_api/token.php by using a POST request
  
<table>
+
{|
<tr><th>Parameter</th><th>Required</th><th>Description</th></tr>
+
|Parameter
<tr><td>client_id</td><td>yes</td><td>The client_id given to your application when you registered it with us</td></tr>
+
|Required
<tr><td>grant_type</td><td>yes</td><td>For initial token generation, this must be set to "authorization_code"</td></tr>
+
|Description
<tr><td>scope</td><td>yes</td><td>The permissions you are requesting access for</td></tr>
+
|-
<tr><td>code</td><td>yes</td><td>The Authorization code you generated.</td></tr>
+
|client_id
</table>
+
|yes
 +
|The client_id given to your application when you registered it with us
 +
|-
 +
|client_secret
 +
|yes
 +
|The client_secret given to your application when you registered it with us
 +
|-
 +
|grant_type
 +
|yes
 +
|For initial token generation, this must be set to "authorization_code"
 +
|-
 +
|scope
 +
|yes
 +
|The permissions you are requesting access for
 +
|-
 +
|code
 +
|yes
 +
|The Authorization code you generated.
 +
|}
  
 
This will return a JSON object with:
 
This will return a JSON object with:
Line 58: Line 97:
 
You may use a refresh token to generate a new access token at https://access.active911.com/open_api/token.php by using a POST request
 
You may use a refresh token to generate a new access token at https://access.active911.com/open_api/token.php by using a POST request
  
<table>
+
{|
<tr><th>Parameter</th><th>Required</th><th>Description</th></tr>
+
|Parameter
<tr><td>client_id</td><td>yes</td><td>The client_id given to your application when you registered it with us</td></tr>
+
|Required
<tr><td>grant_type</td><td>yes</td><td>For refreshing your token, this must be set to "refresh_token"</td></tr>
+
|Description
<tr><td>refresh_token</td><td>yes</td><td>The Refresh token given when you submitted your authorization code.</td></tr>
+
|-
</table>
+
|client_id
 +
|yes
 +
|The client_id given to your application when you registered it with us
 +
|-
 +
|client_secret
 +
|yes
 +
|The client_secret given to your application when you registered it with us
 +
|-
 +
|grant_type
 +
|yes
 +
|For refreshing your token, this must be set to "refresh_token"
 +
|-
 +
|refresh_token
 +
|yes
 +
|The Refresh token given when you submitted your authorization code.
 +
|}
  
 
This will return a JSON object with:
 
This will return a JSON object with:

Revision as of 12:01, 17 February 2014

These are instructions for integrating your app with the Active911 Developer API

Registration

The first step for 3rd party developers is to register your application.

The following information is required to add your client application to our system.

  • Application Name
  • Main Point of Contact - Name, Email, Photo ID, Phone Number
  • Company - Proof of Business Documentation (Business License or other official documentation)
  • Redirect URI - A redirection endpoint which will accept the authorization code generated by our system. This should be the full url of a your endpoint, but we will also accept the base domain name under which your endpoint lives.

You may submit this via email to support@active911.com with the subject line of "Open API Developer Registration"

Once processed, you will receive in return a client_id, a derivative of your Application Name, and client_secret which will be used in requests to our authorization server.

Authorization Code

3rd party applications must use the Authorization Code workflow, starting with a request to https://access.active911.com/open_api/authorize_agency.php by using a GET request.

Parameter Required Description
client_id yes The client_id given to your application when you registered it with us
client_secret yes The client_secret given to your application when you registered it with us
response_type yes Currently we only support the Authorization Code workflow, so this must be set to "code"
redirection_uri yes The url you want the user to be redirected to after they authorize your request
scope yes The permissions you are requesting access for
state no You may set this to a particular value, and that value will be resent upon redirection after authorization

Upon authorization by the user, this will redirect to the redirection uri specified with the authorization code included as a query parameter: <REDIRECTION URI>/?code=<your new authorization code>

Access/Refresh Token Generation

You may exchange the authorization code for an access token and refresh token at https://access.active911.com/open_api/token.php by using a POST request

Parameter Required Description
client_id yes The client_id given to your application when you registered it with us
client_secret yes The client_secret given to your application when you registered it with us
grant_type yes For initial token generation, this must be set to "authorization_code"
scope yes The permissions you are requesting access for
code yes The Authorization code you generated.

This will return a JSON object with: {

 "access_token": "<The access token used to access the api>", 
 "token_type": "Bearer", 
 "expires_in": "<Seconds until the access token expires>" , 
 "refresh_token": "<The refresh token used to get a new access token when this one expires>", 
 "scope": "<The scope of permissions granted to this token.  May be less than the scope requested>"

}

The access token can then be used to access our API. It has a lifetime of 1 day before it expires.

The refresh token can be used to generate new access tokens after the current access token has expired. It has a lifetime of 1 year before it expires.

Refresh Token

You may use a refresh token to generate a new access token at https://access.active911.com/open_api/token.php by using a POST request

Parameter Required Description
client_id yes The client_id given to your application when you registered it with us
client_secret yes The client_secret given to your application when you registered it with us
grant_type yes For refreshing your token, this must be set to "refresh_token"
refresh_token yes The Refresh token given when you submitted your authorization code.

This will return a JSON object with: {

 "access_token": "<The access token used to access the api>", 
 "token_type": "Bearer", 
 "expires_in": "<Seconds until the access token expires>" , 
 "refresh_token": "<The refresh token used to get a new access token when this one expires>", 
 "scope": "<The scope of permissions granted to this token.  May be less than the scope initially requested>"

}