Authenticating with DeepLynx Apps

Prerequisite

You must have created an application - see Create DeepLynx App and have access to its key and secret.

Application

Using the application flow, this is the process for identifying and gaining access tokens for DeepLynx users. This flow is as close as possible to the OAuth2 Authorization Code grant flow, with all parameter names being pulled directly from the specification.

1. Users are redirected from the registered application to the DeepLynx identity provider.
2. Users are either authenticated or registered and logged in by DeepLynx.
3. Users choose to either approve or deny your application's request to act on their behalf.
4. Users are redirected back to your application with a short-lived exchange token.
5. Your application exchanges the short-lived token for a 12-hour access token.

1. Users are redirected to request Identity

Users should be redirected to this url {deeplynxURL}/oauth/authorize with the parameters listed below as query parameters.

response_type	string	required: must contain the value "code" (support for further requests coming soon)
client_id	string	required: the application ID you gained when you created your DeepLynx application
redirect_uri	string	required: indicates the URL to return the user to after authorization is complete
state	string	optional: a random string generated by your application which you can verify later when you exchange the code
scope	string	required: the permissions to request for the user, currently only "all" is supported.
code_challenge	string	optional: DeepLynx supports the PKCE modification of the Authorization Code Flow, include this parameter if you wish to use the PCKE modification. This should be a random string that has potentially been sha256 hashed and base64URL encoded, depending on the code_challenge_method parameter
code_challenge_method	string	optional: must be either plain or S256 if the code_challenge parameter provider has been sha256 hashed and base64URL encoded

2. Users are logged in, authorized, then redirected back to your site by DeepLynx

If a user is able to login (or register) and accepts your authorization request they will be redirected back to your site with a temporary token and the state your provided as query parameters in the URL. You will have 10 minutes to exchange this temporary token for the full access token.

3. Temporary token is exchanged for the full access token

Now that you have your temporary access token, and verified that the state returned matches the original request, you can exchange that token for the full access token. This is done by sending a POST request to {deeplynxURL}/oauth/exchange with the following request body.

grant_type	string	required: value must be authorization_code - support for different requests coming soon
code	string	required: this is the temporary token you just received
redirect_uri	string	required: this is the original redirect uri you sent as part of the original request - included for security purposes
client_id	string	required: this is the application ID you gained when creating the application
client_secret	string	optional: if not including the code_verifier field, you must include the application secret you gained when creating the application
code_verifier	string	optional: if using the PKCE flow, and you included the code_challenge and code_challenge_method parameters in the original request in step one you may include this parameter. This is the raw, unaltered string you included as your code_challenge