Quick start guide to work with Nalanda REST API

This guide will walk you through the process of authenticating with Nalanda REST API using the grant_type=password authorization flow, and how to use the access token (Bearer Token) to make requests to protected API endpoints.

Terms of Use

Please review our API Terms of Use before getting started:

• API Terms of Use

Prerequisites

Before you begin, make sure you have the following:

• A REST API that supports login with the grant_type=password authorization flow.
• Tools like curl or Postman to make HTTP requests.
• Access to the API server and necessary credentials (email, password).

Step 1: Obtaining the Access Token (Bearer Token)

1.1 What is grant_type=password?

The grant_type=password flow is a way to obtain an access token by directly using the user's credentials. This flow is suitable for applications that already have access to the user's credentials (for example, mobile or desktop applications).

1.2 Requesting the Token

To obtain an access token, you need to make a POST request to the API's authorization server. Below is an example using curl.

curl -X POST https://api.nalandaglobal.com/api/open/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD"

1.3 Request Parameters

• grant_type=password: Specifies that the password flow is being used.
• username: The end user's email.
• password: The end user's password.

1.4 Response

The API response will include a JSON object with the access token (Bearer Token):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0NTY3ODkwLCJleHBpcmVkX3N0b3J5X3RpbWUiOiIyMDI1LTA0LTEwVDAwOjA4OjU4WiJ9.mTt0_a1mOCZrXM9f4dOIzYfd7QzYw4FLGGZj3uZfgmk",
  "token_type": "Bearer",
  "expires_in": 3600
}

Make sure to save the access_token value as you will need it to make requests to protected endpoints.

Step 2: Making a GET Request Using the Bearer Token

Once you have the Bearer Token, you can use it to access protected API endpoints. Below is an example of making a GET request to the /api/projects/{id} endpoint using the access token.

2.1 Making a GET Request

Use curl to make a GET request to the /api/projects/{id} endpoint:

curl -X GET https://api.nalandaglobal.com/api/projects/{id}
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Accept: application/vnd.nalanda.api-v1.0+json"

2.2 Request Explanation

• Authorization: Bearer YOUR_ACCESS_TOKEN: This header includes the access token you obtained earlier. It is necessary for authenticating your request.
• Accept: application/vnd.nalanda.api-v1.0+json: This header includes the version of the endpoint requested.

2.3 Response

The response will be a JSON object containing the available projects in the API, something like this:

{
  "id": "01H3KVBK79F0B8FYD2YV85BHVF",
  "code": "001m",
  "description": "My Project",
  "owner_tax_id": "28739205T",
  "builder_tax_id": "28739205J",
  "started_at": "2001-01-01",
  "finished_at": "2001-01-01",
  "project_nature": "Work"
}

Step 3: Handling Errors

You may encounter errors during the process. Some common errors include:

• 401 Unauthorized: This means that the access token is either invalid or has expired. Ensure that the Bearer Token is correctly included in the request header.
• 400 Bad Request: Make sure that all parameters in the token request are correct.

Conclusion

In this guide, you have learned how to authenticate with a REST API using the grant_type=password authorization flow and how to use the Bearer Token to make requests to protected endpoints. You are now ready to start interacting with your API securely.

Happy coding!