Authentication

1. Obtain an Authorization Code

Redirect users to our authorization endpoint to initiate authentication:

Endpoint:

GET https://app.401go.com/api/o/authorize/

Query Parameters:

• response_type=code – The expected response is an authorization code.
• client_id=YOUR_CLIENT_ID – Your application's unique identifier.
• redirect_uri=YOUR_REDIRECT_URI – The URI users are redirected to after authorization.
• scope=REQUESTED_SCOPES – Space-separated permissions (e.g., participant:read participant:write).
• state=YOUR_STATE – A unique value to protect against CSRF attacks (optional but recommended).

Example Request:

https://app.401go.com/api/o/authorize/?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=REQUESTED_SCOPES&state=YOUR_STATE

2. User Authorization

1. Users are redirected to our login page.
2. After login, they are prompted to authorize your application's access to their data.
3. If a user has multiple accounts (e.g., participant, company, advisor), they must select which account to grant access to before proceeding.
4. Upon approval, users are redirected to your registered redirect_uri with an authorization code in the query string:

Example Redirect:

https://YOUR_DOMAIN/redirect_url/?code={auth_code}&state=YOUR_STATE

3. Exchange Authorization Code for Tokens

Make a POST request to the token endpoint to exchange the authorization code for an access token.

Endpoint:

POST https://app.401go.com/api/o/token/

Request Parameters:

• grant_type=authorization_code
• code=AUTHORIZATION_CODE
• redirect_uri=YOUR_REDIRECT_URI
• client_id=YOUR_CLIENT_ID
• client_secret=YOUR_CLIENT_SECRET

4. Use the Access Token

Include the access token in the Authorization header as a Bearer Token in all API requests.

Example Request:

curl -X GET "https://app.401go.com/api/example-endpoint" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json"

• Access tokens are valid for 60 minutes.

5. Optional: Confirm Successful Connection

Make a POST request to the connection success endpoint with your client_id in the request body (form data, not JSON).

6. Refreshing Tokens

When an access token expires, use the refresh token to obtain a new access token.

Endpoint:

POST https://app.401go.com/api/o/token/

Request Parameters:

• grant_type=refresh_token

• refresh_token=YOUR_REFRESH_TOKEN

• client_id=YOUR_CLIENT_ID

• client_secret=YOUR_CLIENT_SECRET

• Refresh tokens are valid for 30 days.

• A new access token will be issued upon success.