Skip to main content

Accessing the API

Sign Up as Facility User​

Start by signing up as a Facility User.

Email and Password​

  1. Navigate to the signup page using the appropriate link for your environment.
  2. Enter your email address.
  3. Create a password. Ensure your password meets the following criteria:
    • At least 8 characters.
    • Includes at least 3 of the following:
      • lowercase letters (a-z),
      • uppercase letters (A-Z),
      • numbers (0-9)
      • special characters (e.g., !@#$%^&*).

Click the "I Manage a Facility" Button​

Once you log in, you will be redirected to a page where you need to click the "I manage a facility" button.

Step 2

Enter Your First and Last Name​

  1. Fill in your first name.
  2. Fill in your last name.

Enter Your Phone Number​

  1. Enter your phone number in the designated field.

Review and Accept Terms and Conditions​

  1. Carefully read through the terms and conditions.
  2. Check the box to acknowledge that you have read and understood them.

Complete the Sign-Up Process​

  1. After accepting the terms and conditions, click the "Continue" button.

You will be redirected to the facilities page

Step 6

With this, you have successfully signed up as a Facility User.

Register your application in the Developer Portal​

Once you have signed up as a Facility User, you can register your application in the Developer Portal

Register new Application​

Application details

Fill in the Application Details​

Application details

Authenticate and obtain a Token​

To call the Nursa APIs you will need a JWT token signed by the Nursa Auth Server, in this step, you have two options:

  • Do you want to integrate with Nursa using a Machine-to-Machine integration? Follow the Machine-to-Machine integration guide.
    • This flow will allow your application to make all the API calls to Nursa API servers and your users will not need to authenticate with Nursa.
  • Do you want your application to interact with Nursa acting like a real user? Follow the User-based integration guide.
    • In this scenario the user with an existing Nursa account Nursa will consent your application to connect to Nursa using their identity. Your app should provide a user interface where the user could connect your app to Nursa by granting permission to your application. This permission grant is performed by the Authorization Code Flow from OAuth2.0.

Machine-to-Machine integration​

  • Obtain a token: Once your application is created on Developer Portal, you need to get the Client ID and Client Secret of your app and call the Get Token API. All the details about the Get Token API are located in Client Credentials Flow under the Authentication section.

  • Refresh your token: The token has an expiration time of 1 hour in production and 24 hours in sandbox, also the Client Credentials grant will not give you a Refresh Token, so to get a new token you need to repeat the first call to the Get Token API with the application credentials. Your application needs to be able to handle an expired token, your code can request a new token for every API call but if this becomes a frequent operation the Nursa Auth Server may block your server due to the Rate Limiting, so we strongly recommend that you use some caching mechanism to store and reuse the token until it is getting close to the expiration time and only then request a new one.

Before going live​

The recommended approach is that you start your integration development and testing in sandbox environment before going to production.

Important information

This type of integration requires communication with the Nursa Team before you start. Due to security reasons, we will enable the Client Credentials grant for your application only upon your specific request.

Actions performed within the Nursa system have to be associated with a user. Our system needs to verify whether the actor has the necessary level of access to perform actions for a particular facility. When the Client Credentials grant is used, the token returned will be missing a user reference. To solve that, our application will automatically associate the request with the application owner’s account. This user, who created the application in the Developer Portal, will be linked to all the actions performed in the system.

We strongly recommend creating a Nursa account using your organization’s name and a generic company email address rather than a personal email. This account should be used to log in to the Nursa Developer Portal and create the application. Alternatively, if an individual email is used, it is important to be aware that the name of the user who created the application may be visible to the Nursa Mobile or Web App users.

Also, it should be noted that the application’s owner account will be associated with all facilities you create/connect with and will have all the permissions to perform actions for those facilities.

User-based integration​

Review the authorization code flow to understand how to obtain the token.

Auth Base URL​

Since Nursa provides two environments for third-party integrators, make sure to use the correct URL to connect to the Nursa Authorization Server:

Audience URL​

Example with Replacements​

Replace {clientId}, {scopes}, and {redirectUri} with your actual values:

<!DOCTYPE html>
<html>
  <head>
    <title>Redirect Button</title>
  </head>
  <body>
    <button onclick="redirectToAuth()">Redirect</button>

    <script>
      function redirectToAuth() {
        const authBaseUrl = "https://auth.sandbox.nursa.com";
        const clientId = "yourClientId";
        const scopes = "yourScopes";
        const redirectUri = "yourRedirectUri";

        const authUrl = `https://${authBaseUrl}/oidc/authorize?client_id=${clientId}&scope=${scopes}&redirect_uri=${redirectUri}&audience=https%3A%2F%2Fpublic-api.sandbox.nursa.com%2F&response_type=code&response_mode=query`;

        window.location.href = authUrl;
      }
    </script>
  </body>
</html>

Steps to Follow​

  1. When the user clicks the "Redirect" button, they will be redirected to the authorization server’s login page.
  2. The user logs in and grants the requested permissions.
  3. After granting permissions, the authorization server redirects the user to the specified redirect_uri with an authorization code.
  4. The client application then exchanges the authorization code for an access token by making a request to the token endpoint.