Obtaining an OAuth Token | Parallel Developer Documentation

This is documentation for Parallel Developer Documentation Legacy – v1.x, which is no longer actively maintained.

For up-to-date documentation, see the latest version (Current – v2.x).

Version: Legacy – v1.x

On this page

The following steps show how your application interacts with Parallel Market's OAuth 2.0 server to obtain a user's consent to perform an API request on the user's behalf. Your application must have that consent before it can execute a Parallel Market API request that requires user authorization.

The list below quickly summarizes these steps:

Your application identifies the permissions it needs.
Your application redirects the user to the Parallel Markets site along with the list of requested permissions (usually via a "Parallel Login" button image click, see our Branding Assets page for button images you can use).
The user decides whether to grant the permissions to your application.
Your application sees what the user decided when they are redirected back to your application.
If the user granted the requested permissions, your application retrieves tokens needed to make API requests on the user's behalf.

Each of these steps is now described in detail in the following sections.

Step 1: Generate Authorization URL

Your first step is to create the authorization request. That request sets parameters that identify your application and define the permissions that the user will be asked to grant to your application.

If you use a client library for OAuth 2.0 authentication and authorization, you create and configure an object that defines these parameters.
If you call the Parallel Market's OAuth 2.0 endpoint directly, you generate a URL and set the parameters on that URL.

Parallel Market's OAuth 2.0 endpoint is at:

https://api.parallelmarkets.com/v1/oauth/authorize

note

This endpoint is accessible only over HTTPS. Plain HTTP connections are refused.

The authorization server supports the following query string parameters for web server applications:

Parameter	Description
`client_id`	Required. Displayed when you create a new OAuth Client in your business settings. Note that the OAuth Client cannot be disabled or authorization will fail.
`redirect_uri`	Required. Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the authorized redirect URIs for the OAuth Client that you provided when creating a new OAuth Client in your settings. If this value doesn't match an authorized URI, the user will be shown an error message. Note that the http or https scheme, case, and trailing slash ('/') must all match.
`scope`	Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These values inform the consent screen that Parallel Markets displays to the user. Valid scopes are listed on the Scopes page. Note that the space delimiter is a requirement of the OAuth 2 protocol specification.
`state`	Required. A random string value that prevents a Cross-Site Request Forgery. It should not be longer than 1024 characters.
`response_type`	Required. This value must be set to `code`.
`force_accreditation_check`	Optional. If the entity is not known to be accredited (for instance, a new account or an expired accreditation), then force users through an accreditation flow after they authenticate. Default is `true`. Ignored if `scope` doesn't include `accreditation_status`. See more details on the Possible Flows page.
`force_identity_check`	Optional. If the entity has not completed a KYC/AML identity process recently then force the user through an identity submission/review flow after they authenticate. Default is `true`. Ignored if `scope` doesn't include `identity`. See more details on the Possible Flows page.
`email`	Optional. User's email to be used to pre-fill the signup page form.
`first_name`	Optional. User's first name to be used to pre-fill the signup page form.
`last_name`	Optional. User's last name to be used to pre-fill the signup page form.
`identity_claim_override_id`	Optional. An integer ID value used to configure custom thresholds for the identity flow. This would be provided by Parallel based on your custom requirements (if any).
`expected_entity_id`	Optional. A connected entity ID used to send a user directly into the desired flow(s) for the User or Business after authenticating, skipping the entity selection step.
`expected_entity_type`	Optional. Either `self` or a `business_type`. Providing `self` will initiate desired flows for the user as an individual (skipping the option to select a business). A `business_type` can be used to send a user directly to the creation page for a new Business after authenticating, with the `expected_entity_type` pre-filled in the form.
`expected_business_name`	Optional. The legal name of a Business. Used with the name of an existing Business to send a user directly into the desired flow(s) for the Business after authentication, skipping the entity selection step. Otherwise, used to send a user directly to the creation page for a new Business, with the `expected_business_name` prefilled in the form.
`handoff_id`	Optional. A unique reference to this handoff which can be used in the Handoff API. Note: only the first 255 characters will be used

Sample redirect URL to Parallel Market's authorization server:

https://api.parallelmarkets.com/v1/oauth/authorize?

scope=accreditation_status%20profile&

state=Z9hLvSULzTSdm&

redirect_uri=https%3A%2F%2Fcrowdfunding.example.com%2Fcallback&

client_id=R1bh416wJQbuGdUFOzSO&

response_type=code

Redirect URI must match

Note that the redirect_uri parameter must exactly match one of the authorized redirect URIs for the OAuth 2.0 client that you provided when creating the client in your business settings, including matching schemes (http:// vs https://) and trailing slashes (i.e., https://example.com/oauth/redirect/ is not the same as https://example.com/oauth/redirect). If this value doesn't match an authorized URI, the user will be shown an error message.

Step 2: Send User to Authorization URL

Redirect the user to the URL you created in Step 1 above. This will initiate the authentication and authorization process. Typically, this occurs when your application first needs to access the user's data. In the case of incremental authorization, this step also occurs when your application first needs to access additional resources that it does not yet have permission to access. Usually, this redirection is initiated via a "Parallel Login" button image click, see our Branding Assets page for button images you can use (see below for an example).

Parallel Market's OAuth 2.0 server authenticates the user and obtains consent from the user for your application to access the requested scopes. The response is sent back to your application using the redirect URL you specified.

Step 3: Parallel Markets prompts user for consent

In this step, the user decides whether to grant your application the requested access. At this stage, Parallel Markets displays a consent window that shows the name of your application and the data (profile information, accreditation documents, etc) that it is requesting permission to access on behalf of the user. The user can then consent or refuse to grant access to your application.

Step 4: Handle the OAuth 2.0 server response

The OAuth 2.0 server responds to your application's access request by redirecting the user to the redirect_uri specified in the original request. The URL parameters will either contain a code value on success, or an error value if the user failed to consent or if there was some other issue.

Success

If the user approves the access request, then the response contains an authorization code. Here's a valid authorization code response example, showing the access code:

https://crowdfunding.example.com/callback?code=8n3yjrbyX83aPkuuv&state=Z9hLvSULzTSdm

Error / Consent Not Granted

If the user does not approve the request or if there is another issue with the request, the response will contain an error code in an error parameter. Here's an example:

https://crowdfunding.example.com/callback?error=access_denied&state=Z9hLvSULzTSdm

The possible error codes are based on the OAuth 2 specification and will be one of these:

Error Code	Description
`invalid_request`	The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
`unauthorized_client`	The client is not authorized to request an authorization code using this method.
`access_denied`	The user declined to grant consent for the scopes requested.
`unsupported_response_type`	The authorization server does not support obtaining an authorization code using the response_type requested.
`invalid_scope`	The requested scope is invalid, unknown, or malformed.
`server_error`	The authorization server encountered an unexpected condition that prevented it from fulfilling the request.

Step 5: Exchange authorization code for refresh and access tokens

After the web server receives the authorization code, it can exchange the authorization code for an access token using the Token API. Once you have an access token, you can make API calls on behalf of the user.