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:

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.
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.
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}

Parameter	Required?	Description
`subdomain`	yes	The subdomain corresponding to the brand where the user is attempting to log in.
`client_id`	yes	The `client_id` credential issued for your application.
`response_type`	yes	For this OAuth flow, the value should always be set to `code`.
`redirect_uri`	yes	The URL where users will be sent after successfully logging in. This must be included in the allowed redirects configured for your application.
`state`	yes	A 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.
`prompt`	no	Values 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

Parameter	Required?	Description
`subdomain`	yes	The subdomain corresponding to the brand where the user is attempting to log in.
`client_id`	yes	The `client_id` credential issued for your application.
`client_secret`	yes	The `client_secret` credential issued for your application.
`code`	yes	The authorization code returned in step 2.
`grant_type`	yes	For this OAuth flow, the value should always be set to `authorization_code`.
`redirect_uri`	yes	The 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:

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.
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.
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.
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}

Parameter	Required?	Description
`subdomain`	yes	The subdomain corresponding to the brand where the user is attempting to log in.
`client_id`	yes	The `client_id` credential issued for your application.
`code_challenge`	yes	The `code_challenge` that was generated based on the `code_verifier` in Step 1.
`code_challenge_method`	yes	We 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_type`	yes	For this OAuth flow, the value should always be set to `code`.
`redirect_uri`	yes	The URL where users will be sent after successfully logging in. This must be included in the allowed redirects configured for your application.
`state`	yes	A 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.
`prompt`	no	Values 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

Parameter	Required?	Description
`subdomain`	yes	The subdomain corresponding to the brand where the user is attempting to log in.
`client_id`	yes	The `client_id` credential issued for your application.
`code_verifier`	yes	The `code_verifier` that was generated in Step 1.
`code`	yes	The authorization code returned in step 2.
`grant_type`	yes	For this OAuth flow, the value should always be set to `authorization_code`.
`redirect_uri`	yes	The 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}

Note: Confidential type clients must also append the client_secret in the above refresh_token request string.

Parameter	Required?	Description
`subdomain`	yes	The subdomain corresponding to the brand where the user is attempting to log in.
`refresh_token`	yes	The `refresh_token` you are exchanging for a new `access_token`.
`grant_type`	yes	For refresh tokens, the value should always be set to `refresh_token`.
`client_id`	yes	The `client_id` credential issued for your application.
`client_secret`	yes*	The `client_secret` credential issued for your confidential client type application. *This parameter is not needed for public client types.

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 flow#

Overview#

Step 1: Authorization Redirect#

Step 2: Callback#

Step 3: Token Request#

Authorization Code w/ PKCE flow#

Overview#

Step 1: Code Verifier#

Step 2: Authorization Redirect#

Step 3: Callback#

Step 4: Token Request#

Authenticating Requests#

Refresh Tokens#

Authorization Code flow

Overview

Step 1: Authorization Redirect

Step 2: Callback

Step 3: Token Request

Authorization Code w/ PKCE flow

Overview

Step 1: Code Verifier

Step 2: Authorization Redirect

Step 3: Callback

Step 4: Token Request

Authenticating Requests

Refresh Tokens