Authentication with OAuth

Authorization Code flow

The Authorization Code flow should be used by web applications that execute on a server and can keep the client_secret value confidential. Before starting, make sure that you have been issued the correct credentials.

View an example implementation of the Authorization Code flow


Overview

From a high level, users authenticate with this flow as follows:

  1. User initiates the login flow by either by clicking a link or navigating to the app log in page. This should redirect them to Mariana Tek for authorization. If necessary, the user will log in and give permission to your application to make requests on their behalf.
  2. After authenticating, the user is redirected to the redirect_url your application provided as part of Step 1, with the authorization code returned as a query parameter.
  3. This authorization code can then be exchanged for an access_token by making a request to the token endpoint.

Once these steps are complete, the access token may be stored and used to authenticate subsequent API requests.


Step 1: Authorization Redirect

To begin the flow, you'll need to construct the authorization redirect URL. This URL is determined by several parameters:

https://{SUBDOMAIN}.marianatek.com/o/authorize?response_type=code
&client_id={CLIENT_ID}
&redirect_uri={REDIRECT_URI}
&state={STATE}
ParameterRequired?Description
subdomain yesThe subdomain corresponding to the brand where the user is attempting to log in.
client_idyesThe client_id credential issued for your application.
response_typeyesFor this OAuth flow, the value should always be set to code.
redirect_uriyesThe URL where users will be sent after successfully logging in. This must be included in the allowed redirects configured for your application.
stateyesA value that will be returned along with the authorization code in the response and can be used by your app to maintain state between the authorization request and callback. To prevent CSRF attacks, you should verify that the state in the response matches the value provided in this request.
promptnoValues are True and False. Indicates whether Mariana Tek should require the user to log in even if the user already has an active session.

The user should be redirected to this URL to begin the flow. If the user already has an active session and you have not set the prompt query parameter to True, then the user will not prompted to log in again and will be immediately redirected back to the redirect_uri, allowing for a seamless experience switching between applications.

Step 2: Callback

After Step 1 has been completed successfully, the user will be sent to the redirect_uri that was specified with the authorization code and state set as query parameters. The redirect will look like this:

https://my-app.com/callback?code={AUTHORIZATION_CODE}&state={STATE}

You will need the value for the authorization code to complete Step 3.

To prevent CSRF attacks, you should verify that the value of state matches the one you set as part of Step 1.

Step 3: Token Request

Now that you have an authorization code, you should retrieve an access token that can be used to make authenticated requests with Mariana Tek APIs. This URL can be constructed from a few parameters:

POST https://{SUBDOMAIN}.marianatek.com/o/token/?client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&code={AUTHORIZATION_CODE}
&grant_type=authorization_code
ParameterRequired?Description
subdomain yesThe subdomain corresponding to the brand where the user is attempting to log in.
client_idyesThe client_id credential issued for your application.
client_secretyesThe client_secret credential issued for your application.
codeyesThe authorization code returned in step 2.
grant_typeyesFor this OAuth flow, the value should always be set to authorization_code.
redirect_uriyesThe URL provided as part of step 1. If your app only has one redirect_uri configured, that value is used as a default.

The response will look like this:

{
"access_token": {ACCESS_TOKEN},
"expires_in": 604800,
"token_type": "Bearer",
"scope": "read:account",
"refresh_token": {REFRESH_TOKEN},
}

Authorization Code w/ PKCE flow

The Authorization Code w/ PKCE flow should be used by Single Page Applications and mobile applications, since they cannot keep the client_secret value confidential. Before starting, make sure that you have been issued the correct credentials.

View an example implementation of the Authorization Code w/ PKCE flow.


Overview

This flow is very similar to the Authorization Code flow, with a few modifications to accomodate the Proof Key for Code Exchange (PKCE) extension. From a high level, users authenticate with this flow as follows:

  1. User initiates the authentication flow either by clicking a link or navigating to the app log in page. This should trigger the generation of the code_verifier and code_challenge.
  2. The user should be redirected to the authorization URL. If necessary, the user will log in and give permission to your application to make requests on their behalf.
  3. After authenticating, the user is redirected to the redirect_url your application provided as part of Step 1, with the authorization code returned as a query parameter.
  4. The authorization code and code_verifier can then be exchanged for an access_token by making a request to the token endpoint.

As in the basic Authorization Code flow, once these steps are complete the access token may be stored and used to authenticate subsequent API requests.


Step 1: Code Verifier

After the user has initiated the flow, your app will need to generate a random value to use as a code_verifier. You will also need to generate the code_challenge, which may be either the Base64URL encoded SHA256 hash of the code_verifier(recommended) or the plain code_verifier. The value of the code_verifier should be stored temporarily in a place that can be accessed later on in the flow (e.g. cookies).


Step 2: Authorization Redirect

To continue the flow, you will need to construct the authorization redirect URL. This URL is determined by several parameters:

https://{SUBDOMAIN}.marianatek.com/o/authorize?response_type=code
&client_id={CLIENT_ID}
&code_challenge={CODE_CHALLENGE}
&code_challenge_method=S256
&redirect_uri={REDIRECT_URI}
&state={STATE}
ParameterRequired?Description
subdomain yesThe subdomain corresponding to the brand where the user is attempting to log in.
client_idyesThe client_id credential issued for your application.
code_challengeyesThe code_challenge that was generated based on the code_verifier in Step 1.
code_challenge_methodyesWe recommend that this is always set to S256, which indicates that the code_challenge is the SHA256 hash of the code_verifier. This may also be set to plain if the challenge is sent as the plain verifier.
response_typeyesFor this OAuth flow, the value should always be set to code.
redirect_uriyesThe URL where users will be sent after successfully logging in. This must be included in the allowed redirects configured for your application.
stateyesA value that will be returned along with the authorization code in the response and can be used by your app to maintain state between the authorization request and callback. To prevent CSRF attacks, you should verify that the state in the response matches the value provided in this request.
promptnoValues are True and False. Indicates whether Mariana Tek should require the user to log in even if the user already has an active session.

As in the Authorization Code flow, after being redirected to the authorize URL if the user already has an active session and you have not set the prompt query parameter to True, then the user will not prompted to log in again and will be immediately redirected back to the redirect_uri, allowing for a seamless experience switching between applications.

Step 3: Callback

After Step 2 has been completed successfully, the user will be sent to the redirect_uri that was specified with the authorization code and state set as query parameters. The redirect will look like this:

https://my-app.com/callback?code={AUTHORIZATION_CODE}&state={STATE}

You will need the value for the authorization code to complete Step 3.

To prevent CSRF attacks, you should verify that the value of state matches the one you set as part of Step 1.

Step 4: Token Request

Now that you have an authorization code, you should use this code and the code verifier generated in Step 1 to retrieve an access token that can be used to make authenticated requests with Mariana Tek APIs. This URL can be constructed from a few parameters:

POST https://{SUBDOMAIN}.marianatek.com/o/token/?client_id={CLIENT_ID}
&code_verifier={CODE_VERIFIER}
&code={AUTHORIZATION_CODE}
&grant_type=authorization_code
ParameterRequired?Description
subdomain yesThe subdomain corresponding to the brand where the user is attempting to log in.
client_idyesThe client_id credential issued for your application.
code_verifieryesThe code_verifier that was generated in Step 1.
codeyesThe authorization code returned in step 2.
grant_typeyesFor this OAuth flow, the value should always be set to authorization_code.
redirect_uriyesThe URL provided as part of step 1. If your app only has one redirect_uri configured, that value is used as a default.

The response will look like this:

{
"access_token": {ACCESS_TOKEN},
"expires_in": 604800,
"token_type": "Bearer",
"scope": "read:account",
"refresh_token": {REFRESH_TOKEN},
}

Authenticating Requests

Mariana Tek's APIs use bearer auth for authenticating requests. After completing the OAuth flow and retrieving an access_token, subsequent requests should look like this:

curl -H "Authorization: Bearer {access_token}" http://myapp.sandbox.marianatek.com/api/users/self

Refresh Tokens

Access tokens will no longer be valid for making requests after they have expired. After expiration, you can retrieve another access_token for the user using the refresh_token that is also contained in the token reponse. To exchange a refresh_token for a new access_token, the request should look like this:

POST https://{SUBDOMAIN}.marianatek.com/o/token/?refresh_token={REFRESH_TOKEN}
&grant_type=refresh_token&client_id={CLIENT_ID}
ParameterRequired?Description
subdomain yesThe subdomain corresponding to the brand where the user is attempting to log in.
refresh_tokenyesThe refresh_token you are exchanging for a new access_token.
grant_typeyesFor refresh tokens, the value should always be set to refresh_token.
client_idyesThe client_id credential issued for your application.

The response will look like this:

{
"access_token": {ACCESS_TOKEN},
"expires_in": 604800,
"token_type": "Bearer",
"scope": "read:account",
"refresh_token": {REFRESH_TOKEN},
}