Skip to page content
Secretary of Labor Hilda L. Solis
DOL Home > OPEN > Developer Community > Request Authorization

Request Authorization

API Key Registration

To make requests to the API service you must register at https://webapps.dol.gov/developer and create an API key for each application that will access the API. As part of the key generation process you must assign a shared secret to each key in order to sign every API request.

Request Authorization

All requests must include an authorization header to authorize the request.

You must add a request header named Authorization that contains a timestamp, your API Key and a signature. Each individual item is created as follows:

Timestamp

The timestamp format shall be ISO 8601. Each date and time value has a fixed number of digits that must be padded with leading zeros. The timestamp shall be provided using the UTC time zone. The date format shall be yyyy-MM-ddThh:mm:ssZ

yyyy =  four digit year (e.g. 2011)
MM = two digit month, padded if less than 10 (e.g. 04)
dd = two digit day, padded if less than 10 (e.g. 09)
T = Time separator (always T)
hh = two digit hour, in 24hr format, padded if less than 10 (e.g. 18)
mm = two digit minute, padded if less than 10 ( e.g. 09 )
ss = two digit second, padded if less than 10 ( e.g. 00 )
Z = timezone (always T which means UTC)

Example:

Request from a client to the service on March 9th, 2011 at 6:09:00 PM. Local time zone is ADT (or UTC -4).
To create a valid time stamp you shall:

  1. Convert time to UTC – Results in March 9th, 2011 at 10:09 PM
  2. Apply the  yyyy-MM-ddThh:mm:ssZ format –

Results in 2011-03-09T22:09:00Z

*Note: To accommodate for small differences on clocks and prevent request forgery there is a 15-minute window for valid timestamps to be accepted by the server.

API Key

The API key is provided to identify an application that requests data from the DOL Data API. You must register at [Registration URL] and create an API key for each application that accesses the API. This key must be provided with every request as part of the authorization header. The API keys are auto-generated in a standard GUID format. An example API key is 21EC2020-3AEA-1069-A2DD-08002B30309D

Signature

Each request must contain a signature to authenticate that the owner of the API key is the one making the request. The signature is computed using the HMAC-SHA1 algorithm providing the API key’s Shared Secret as the secret key and the Authorization header as the input.

Example:

You want to read data from table Agencies in the dataset named FORMS.

The request URL is: http://api.dol.gov/V1/FORMS/Agencies
Your API Key is d9c6c290-da4c-424e-a378-fb4bd027b58b
Your shared secret is mysecret11111111111
Local time is March 9th, 2011 at 6:09:00 PM UTC-4

Steps:

  1. Calculate timestamp (see timestamp section): 2011-03-09T22:09:00Z
  2. Build an authorization string using the request URI and appending the timestamp and API Key values. The URI must not include the top-level domain. Field names must be labeled Timestamp and ApiKey respectively and must be appended by the “&” character. This string is case sensitive.

    Resulting Authorization String:
    /V1/FORMS/Agencies&Timestamp=2011-03-09T22:09:00Z&ApiKey=d9c6c290-da4c-424e-a378-fb4bd027b58b
  3. Pass the string through the HMAC-SHA1 algorithm using the shared secret as a key. Signature = HMAC-SHA1(Authorization String) using key mysecret11111111111

    Signature = CALCULATED SIGNATURE

Authorization Header

The Authorization header must be supplied with every request. It is composed of the Timestamp, ApiKey, and Signature values as specified in this document.

The “Authorization” header must be set to Timestamp={0}&ApiKey={1}&Signature={2} where {0}, {1}, and {2} are the values for Timestamp, API Key, and Signature respectively. The values must be calculated as specified in this document.

Example:

You want to read data from table Agencies in the dataset named FORMS.

The request URL is: http://api.dol.gov/V1/FORMS/Agencies
Your API Key is d9c6c290-da4c-424e-a378-fb4bd027b58b
Your shared secret is mysecret11111111111
Local time is March 9th, 2011 at 6:09:00 PM UTC-4

Steps:

  1. Calculate timestamp (see timestamp section): 2011-03-09T22:09:00Z
  2. Calculate signature (see signature section): CALCULATED SIGNATURE
  3. Create Authorization header:
    Timestamp=2011-03-09T22:09:00Z&ApiKey=d9c6c290-da4c-424e-a378-fb4bd027b58b &Signature=CALCULATED SIGNATURE
  4. Append a header to the request named “Authorization” and set its value to the calculated result. The service will validate your request using a similar process and respond with the data requested.

Response Formats - XML and JSON

The API is capable of returning results in both XML and JSON formats. XML is the default type returned if a type is not specified. To request results in JSON format you must modify the “Accept” header of the request and set it to application/json. If the Accept header is not present XML data will be returned.