Authentication Guide

Introduction

In this document, we'll explore how to securely authenticate and authorize applications to access. Rose Rocket using OAuth 2.0. By leveraging OAuth 2.0, developers can empower their applications to seamlessly interact with Rose Rocket's API on behalf of end-users This guide outlines the authentication process, providing detailed instructions on obtaining access tokens through direct application integration.

Note: To get access to our APIs, there are two ways:

If you are an existing Rose Rocket customer, you can obtain API access by directly contacting your account representatives. They can help you through the process and provide you with the necessary credentials.
If you are an Independent Software Vendor (ISVs), you can reach out to our Partnership team <email ID> for access.

Two Ways to Authenticate

Obtaining OAuth Credentials
Enabling a Service Account

1. Obtaining OAuth Credentials

Step 1: Register an Application.

To begin, you must signup on the developer portal to obtain OAuth 2.0 credentials from Rose Rocket to be able to make OAuth 2.0 requests.

General Prerequisites:
client_id: The unique identifier assigned to your application by Rose Rocket. client_secret: A confidential token also provided by Rose Rocket upon application registration.

Configure Callback URIs (REDIRECT_URI) during registration where Rose Rocket will send the authorization code after the end-user consents. These are the URLs where users will be redirected after authentication.

Initiating the Authorization Code Grant Type Flow
Step 2: Construct Authorization Request.

To initiate the OAuth 2.0 authorization code grant flow, your application must redirect the user to Rose Rocket's authorization endpoint. The authorization endpoint for Rose Rocket is: https://a.roserocket.com/authorize
Construct a URL with the necessary query parameters and redirect the user's browser to this URL. This URL should include the following parameters:
audience: The intended recipient of the token, which is always set to the base URL of the Rose Rocket API https://roserocket.com. response_type=code: Indicates that your application is requesting an authorization code. client_id: The unique identifier assigned to your application by Rose Rocket. redirect_uri: The URI where Rose Rocket will send the user after successful authorization. scope: The access scope required by the application is and should be formatted as: offline_access email profile state: A unique value generated by your application to prevent CSRF attacks.

Example authorization URL:

https://a.roserocket.com/authorize?audience=https://roserocket.com&scope=offline_access%20email%20profile&response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={generated_state_value}

Note: Make sure to replace {CLIENT_ID}, {CLIENT_SECRET}, {REDIRECT_URI} with the provided credentials. Secure and save them in a folder for the later steps.

Step 3: User Authentication

The user’s browser will be initially redirected to a page where they can log in through a social authentication connection. Alternatively, a 3rd party identity provider (such as Azure Active Directory) can be used.

Note: Contact Rose Rocket for assistance configuring an identity provider.

Receiving the Authorization Code
Step 4: Redirect and Retrieve Authorization Code.

After successful authentication, the user's browser is redirected to the specified REDIRECT_URI with the authorization code. The REDIRECT_URI will include two query parameters:

state: The same value sent in the authorization request to validate the response.
code: A one-time use code that can be exchanged for an access token.

Generating Access and Refresh Tokens
Step 5: Exchange Authorization Code for Tokens.

You make a POST request to the Rose Rocket Token endpoint to exchange the authorization code for an access token. This will include the following parameters.

grant_type: authorization_code
client_id: CLIENT_ID
client_secret: CLIENT_SECRET
code: the authorization code received in the previous step.
redirect_uri: REDIRECT_URI

Example cURL request:

curl --request POST \
     --url 'https://a.roserocket.com/oauth/token' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=authorization_code \
     --data 'client_id={CLIENT_ID}' \
     --data 'client_secret={CLIENT_SECRET}' \
     --data 'code={code}' \
       --data 'redirect_uri={REDIRECT_URI}'

Note: Make sure to replace {CLIENT_ID}, {CLIENT_SECRET}, {REDIRECT_URI} with the provided credentials. Secure and save them in a folder for the later steps.

Using the Access Token
Step 6: Accessing the API.

Use the access token to authenticate API requests to the Rose Rocket platform. Include the token in the Authorization header as a Bearer token.

Example of API request with access token:

curl --request GET
  --url '<https://network.roserocket.com/api/v1/me'>
  --header 'Authorization: Bearer ACCESS_TOKEN'

Refreshing the Access Token
Step 7: Using the Refresh Token (Optional).

Access tokens are typically short-lived for security reasons. When the access token expires, your application will receive a 401 status code indicating that the token is no longer valid. At this point, you should use the refresh token to obtain a new access token by making a POST request with:

grant_type set to refresh_token

Example of using the refresh token to get a new access token:

curl --request POST
  --url '<https://a.roserocket.com/oauth/token'>
  --header 'content-type: application/x-www-form-urlencoded'
  --data 'grant_type=refresh_token'
  --data 'refresh_token=REFRESH_TOKEN'
  --data 'client_id=CLIENT_ID'
  --data 'client_secret=CLIENT_SECRET'
  --data 'org_id=TargetOrgID'

By following these steps, developers can securely integrate with the Rose Rocket API using OAuth 2.0. This process ensures that access is granted in accordance with the user's consent.

2. Enabling a Service Account

Under the Applications create a new Oauth Application
This will create a new OAuth Application tied to your Organization. This will contain a Client ID, Client Secret that will allow you to set up access through the Web Authentication flow.
Select Accounts and select Create a New Account
This will create a new Service Account that will reside under your Users and have the access granted under your Application.

Note: This will be defaulted to the Manager Role

Test this flow by selecting Request Details

This will provide an example of the request as a HTTP or cURL command for you to run.

Example cURL:

curl --location 'https://a.roserocket.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"grant_type":"client_credentials",
"client_id":"{client_id}",
"client_secret":"{client_secret}",
"audience":"https://roserocket.com",
"org_id":"{org_id}",
"user_id":"{service_account_user_id}"
}'

By running this command it will then return a valid Token to access your Application.

Troubleshooting

When working with our APIs, it is important to ensure that your authentication process is set up correctly. If you encounter any issues, below are some of the key points to check:

✅ Check Request Parameters: Ensure that all required parameters are correctly specified in your request. Verify that the client_id and client_secret are accurate.
✅ Application Provisioned: Double check that you have specified the correct callback URLs or redirect URIs.
✅ Redirect URI: Ensure that your application is listening at the redirect URI.