Skip to main content
Version: 1.0

Authentication

PDK supports the client credentials and authorization code flows defined in the OAuth 2.0 specification.

Client Credentials

The client credentials flow allows your application to access PDK without a user. Most integrations use this flow due to its simplicity.

  • Users grant authorization by adding a permission in PDK using the email address assigned to your application. This permission acts as a service account within an organization and will not be affected by personnel changes.
  • Tokens provide access to all organizations that have authorized your application. New tokens are obtained by providing your client_id and client_secret.
  • Events are attributed to your application generally rather than to specific users.

Step 1: Authorize your application

In order to access a PDK organization, a user within that organization must add a permission for your application. In the animation below, the email address assigned to the application is pdk@example.com.

Authorization Animation

Step 2: Retrieve an ID token

You can now retrieve an ID token that provides access to all organizations that have authorized your application.

Request

POST https://accounts.pdk.io/oauth2/token HTTP/1.1
Authorization: Basic {{credentials}}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
ParameterLocationTypeRequiredDescription
credentialsHeaderStringYesBase64-encoded credentials: {{client_id}}:{{client_secret}}.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"token_type": "Bearer",
"access_token": "NmQ5MWIzNm...Ve6g9Lpv4w",
"id_token": "eyJhbGciOi...9PUxVsmQUQ",
"expires_in": 300
}
PropertyTypeDescription
token_typeStringThe token type. This will always be set to Bearer.
access_tokenStringThe access token. This token is not used.
id_tokenStringAn ID token. This token can be used to authenticate subsequent API calls.
expires_inIntegerThe number of seconds before the ID token expires.

Authorization Code

The authorization code flow allows your application to access PDK on behalf of a user. This flow is less common, but it's useful if your application needs to be able to distinguish between multiple API users within the same organization.

  • Users grant authorization by entering their PDK credentials in a web view managed by your application.
  • Tokens only provide access to organizations that are accessible to the authenticated user. New tokens are obtained by providing your client_id and client_secret along with a user-specific refresh_token.
  • Events are attributed to specific users who authorize your application.

Step 1: Display the login page

In order to authenticate a specific user, your application must display a web view and load the PDK login page using the URL below.

https://accounts.pdk.io/oauth2/auth?client_id={{client_id}}&redirect_uri={{redirect_uri}}&scope={{scope}}&prompt=consent&response_type=code&state=abc123
ParameterLocationTypeRequiredDescription
client_idQueryStringYesYour client ID.
redirect_uriQueryStringYesA URL-encoded redirect URI. This must match one of the redirect URIs registered for your application. Requests to add or remove redirect URIs should be emailed to integrations@prodatakey.
scopeQueryStringYesA list of scopes. Possible values include openid if a refresh token isn't needed or openid+offline_access if a refresh token is needed.
promptQueryStringYesIf a refresh token is needed, then this parameter is required and its value must be set to consent.
response_typeQueryStringYesThe response type. This value should be set to code.
stateQueryStringNoURL-encoded state information specific to your application.

Step 2: Retrieve the authorization code

After entering their credentials, users will be redirected back to your application according to the redirect URI. Your application can then retrieve the authorization code from the query string.

https://example.com/?code=YjU5MzEwNz...BcKeRZgC4A&state=abc123
PropertyTypeDescription
codeStringThe authorization code.
stateStringURL-encoded state information specific to your application.

Step 3: Retrieve an ID token

You can now retrieve an ID token that provides access to all organizations that are accessible to the authenticated user.

Request

POST https://accounts.pdk.io/oauth2/token HTTP/1.1
Authorization: Basic {{credentials}}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code={{code}}&redirect_uri={{redirect_uri}}
ParameterLocationTypeRequiredDescription
credentialsHeaderStringYesBase64-encoded credentials: {{client_id}}:{{client_secret}}.
grant_typeBodyStringYesThe grant type. This value should be set to authorization_code.
codeBodyStringYesThe authorization code.
redirect_uriBodyStringYesA URL-encoded redirect URI. This must match the redirect URI used to obtain the authorization code.

Response

The response includes an ID token and a refresh token (if requested).

HTTP/1.1 200 OK
Content-Type: application/json

{
"token_type": "Bearer",
"id_token": "eyJhbGciOi...DHuhSu7aEw",
"expires_in": 300,
"refresh_token": "Yzg4NzRjOW...wPVW5vKE1Q",
"access_token": "Y2ViZjY0OD...e3n0RuJiEs"
}
PropertyTypeDescription
token_typeStringThe token type. This will always be set to Bearer.
id_tokenStringAn ID token. This token can be used to authenticate subsequent API calls.
expires_inIntegerThe number of seconds before the ID token expires.
refresh_tokenStringThe refresh token. This token can be exchanged for a new user-scoped ID token. It never expires but can only be used once.
access_tokenStringThe access token. This token is not used.

Step 4: Use the refresh token

Once an ID token expires, a refresh token can be used to retrieve a new one.

Request

POST https://accounts.pdk.io/oauth2/token HTTP/1.1
Authorization: Basic {{credentials}}
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token={{refresh_token}}
ParameterLocationTypeRequiredDescription
credentialsHeaderStringYesBase64-encoded credentials: {{client_id}}:{{client_secret}}.
grant_typeBodyStringYesThe grant type. This value should be set to refresh_token.
refresh_tokenBodyStringYesThe refresh token returned in the previous step.

Response

The response includes a new ID token as well as a new refresh token, which can be used again for perpetual access.

HTTP/1.1 200 OK
Content-Type: application/json

{
"token_type": "Bearer",
"id_token": "eyJhbGciOi...VrfKfscImA",
"expires_in": 300,
"refresh_token": "MWI2NmYxMW...aWajGjiaaW",
"access_token": "YWRhNjQwNz...bPpSCXGHmg"
}
PropertyTypeDescription
token_typeStringThe token type. This will always be set to Bearer.
id_tokenStringThe ID token. This token can be used to authenticate subsequent API calls.
expires_inIntegerThe number of seconds before the ID token expires.
refresh_tokenStringThe refresh token. This token can be exchanged for a new user-scoped ID token. It never expires but can only be used once.
access_tokenStringThe access token. This token is not used.