RELAYTO API - Authentication

Register your application with RELAYTO

RELAYTO invites select developers to integrate their applications with RELAYTO/ Document Experience Platform. Please email [email protected] with the following details:

• Name of the application
• Authentication Redirect Callback URL (YOUR_REDIRECT_URL).
  URL must start with https://, e.g. https://yourcompanydomain.com/callback
  During the OAuth2 authentication flow will receive AUTHORIZATION_CODE as a query string parameter in the callback URL.

RELAYTO will issue YOUR_CLIENT_ID & YOUR_CLIENT_SECRET for your application that you'll need to use to get a user access token for your application.

1. Implement RELAYTO "Sign up/Sign in" 

In your application, you would need to allow users to "Sign up/Sign in" to RELAYTO. To enable seamless authentication flow, hyperlink RELAYTO "Sign up/Sign in" button to the following URL:

https://relayto.com/signin?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&response_type=code&code_challenge=YOUR_CODE_CHALLENGE

 IMPORTANT 
YOUR_REDIRECT_URL should be the same as what you submitted in the first step
YOUR_CODE_CHALLENGE and should be validated according to RFC-7636 @see

2. Obtain an authorization code

After a user has successfully Signed In to RELAYTO, the browser will redirect you to YOUR_REDIRECT_URL with the AUTHORIZATION_CODE  You will need to use AUTHORIZATION_CODE to get USER_ACCESS_TOKEN in the next request.

Redirect URL after user sign in/sign up:

YOUR_REDIRECT_URL?code=AUTHORIZATION_CODE

Example of the Redirect URL with an Authorization Code:

https://yourcompanydomain.com/?code=def50200a6292c72FRer...

3. Get a user access token

After acquiring AUTHORZATION_CODE you can request USER_ACCESS_TOKEN. You would need USER_ACCESS_TOKEN to make all authenticated API requests to RELAYTO. YOUR_CODE_VERIFIER should be the same as YOUR_CODE_CHALLENGE. When you are getting, you also get USER_REFRESH_TOKEN to renew USER_ACCESS_TOKEN in the background, without a need for the user to re-authenticate in RELAYTO.

Request to get USER_ACCESS_TOKEN:

curl -X POST \
https://relayto.com/api/oauth2/access_token \
-H 'content-type: application/x-www-form-urlencoded' \
-d grant_type=authorization_code
-d client_id=YOUR_CLIENT_ID
-d client_secret=YOUR_CLIENT_SECRET
-d code=AUTHORIZATION_CODE
-d redirect_uri=YOUR_REDIRECT_URL
-d code_verifier=YOUR_CODE_VERIFIER

Response:

{
   "token_type": "Bearer",
   "expires_in": 3600,
   "access_token": USER_ACCESS_TOKEN,
   "refresh_token": USER_REFRESH_TOKEN
}

Refreshing a user access token

Use USER_REFRESH_TOKEN to refresh the USER_ACCESS_TOKEN in the background.

Request to get USER_ACCESS_TOKEN:

curl -X POST \
https://relayto.com/api/oauth2/access_token \
-H 'content-type: application/x-www-form-urlencoded' \
-d grant_type=refresh_token
-d client_id=YOUR_CLIENT_ID
-d client_secret=YOUR_CLIENT_SECRET
-d refresh_token=USER_REFRESH_TOKEN

Response:

{
   "token_type": "Bearer",
   "expires_in": 3600,
   "access_token": USER_ACCESS_TOKEN,
   "refresh_token": USER_REFRESH_TOKEN
}