Developers / API Documentation / Resources / Petitions

Authorization Keys on Petitions

POST petitions/:petition_id/auth_keys

Sends a request for a petition authorization key on behalf of an individual.

The requester must provide a source code, specified by source, for their request. This source code indicates where signatures (or other requests on the petition) are coming from. source must be unique for each requester, so URL would most often be a reasonable source code (e.g. a specific YouTube video).

Request Parameters

Parameter Name Type Description
petition_id int (In URL) The petition on which authorization is being requested.
source_description string User defined. The type of media around which signatures will be gathered. Example: "YouTube video"
source string URL or other identifier of the source from which signatures will be gathered. Must be unique to the API consumer submitting the request. Example:
requester_email string The email address of the individual requesting the petition authorization key.
callback_endpoint string The URL to which the petition authorization key or other information (outlined below) will be posted.

Response Data

A 202 acknowledgement response is sent upon receipt of the request if no petition authorization key already exists for this resource and requestor. If it does, then a 200 response is sent with the authorization code that already exists or an indication that the request has been denied or that a previously-granted authorization code has been revoked.

The following is the data sent to the callback endpoint once the request has been processed. The originally fields submitted are posted to the callback endpoint to enable the user submitting the request to map the authorization back to its own user and resource (originally specified in source).

Field Name Type Description
status string Whether or not the authorization key was granted. Possible values are granted, denied, or revoked.
petition_id int The ID of the petition on which an authorization key was requested.
source_description string The source_description originally submitted with this request.
source string The source originally submitted with this request.
requester_email string The requester_email originally submitted with this request.
auth_key string (If granted or revoked) The petition authorization key.


"source_description": "YouTube video",
"source": "",
"requester_email": "",
"callback_endpoint": ""

Results in a 202 acknowledgment response. Eventually, the callback endpoint would receive this request:

"status": "granted",
"petition_id": "48503",
"source_description": "YouTube video",
"source": "",
"requester_email": "",
"auth_key": "29b109add0012f47754a28309b670a2c"

Note: A public API key is a required parameter on all requests, and a timestamp, endpoint, and request signature are required on certain requests. For readability, these parameters have been omitted from the tables and examples above.