Authentication

OAuth 2.0

OAuth 2.0 is a protocol and focuses on client developer simplicity while providing specific authorization flows for web applications. Nmbrs’s API supports the authorization code grant type using the standard authorization code flow. The standard flow is the most well known OAuth 2.0 flow and typically used by web server applications. It requires your app to securely use and store a client secret.

OAuth URLs


Discovery endpoint                     https://identityservice.nmbrs.com/.well-known/openid-configuration
Base authorization URL             https://identityservice.nmbrs.com/connect/authorize
Token URL                                      https://identityservice.nmbrs.com/connect/token
Revocation URL                            https://identityservice.nmbrs.com/connect/revocation

Checklist - do you have all the necessary information to authenticate?

Below is the list of the necessary data you need to authenticate to the API:

  • client_id                                  Provided by Nmbrs, after filling the "Register your app!" form 

  • client_secret                          Provided by Nmbrs, after filling the "Register your app!" form 

  • redirect_uri                            Informed by the client in the "Register an app!" form

  • subscription key                    Generated on the developer portal when subscribing to a product

NO   If you still don't have some of the data in hands, please go back to Getting Started and go through the instructions.

YES!  Great! Follow the Step by step:

Terminology

It's important for everyone to be on the same page regarding the terminology that will be used on this documentation.

  • Client: any app that wants to a integrate with Nmbrs data. A user must grant permission before the client can access any data.

  • Provider: provides the resources to be used by the client, the API itself, the authentication, etc.

  • API: Nmbrs REST API, which the client can use to read and modify Nmbrs data.

  • User: Nmbrs customer which gives consent for the app to access it's data.

  • Authorization code: A temporary code issued by us when the user grants you (your client) access to their data. This code is only valid for 5 minutes, you do not need to persist it on your side. You will exchange this for an access token and refresh token immediately after obtaining it.

  • Access token: A JSON Web Token (JWT) that you use to authenticate to our API on behalf of the user. These tokens are credentials and they should be treated as such. You can decode the access token in order to access it's claims (link to claims). The access token can be reused and it is valid for 1 hour.

  • Refresh token: You can exchange the refresh token to get a new access token when it expires. The refresh token as a longer expiration time: 30 days but can only be used once. Every time you exchange it for an access token you will receive a new refresh token. With this mechanism, the user only needs to grant the consent once.

Scopes

The list with all possible scopes and what they mean can be found at Scopes.

1. Get the authorization code

In order to receive the authorization code, users will need to first give consent. You will need to provide a button that redirects the user to the below url:

https://identityservice.nmbrs.com/connect/authorize?
client_id={{clientId}}
&state={{state}}
&scope={{scopes}}
&response_type=code
&redirect_uri={{redirect_uri}}

What you will need:

client_id /client_secret    Generated by Nmbrs and shared after filling the register an app form

state                     Used to mitigate CSRF attacks primarily, it should be a unique and
                                                         non-guessable value. It allows you to verify that the value coming rom the
                                                         response matches the one you sent

redirect_uri               URL registered when creating the application. This is where the user will be redirected after giving consent. We will sent the authorization code, consented scopes and the state as query string. This will be a web page on your application where you can access the user's session in the backend and read the query parameters.

scope                     You need to send the chosen scopes needed

Example:

https://identityservice.nmbrs.com/connect/authorize?
client_id=7xr7NV9yqcUz*r2C$ey6
&state=9e530228-7e2b3ff6dcdd
&scope=employee.employment.read employee.info.read  employee.payment company.info company.info.read company.payrollsettings.read offline_access
&response_type=code
&redirect_uri=https://redirecturlapp.com

For testing you can use redirect_uri=http://localhost:8080

When the user clicks on the button with reference to the URL above, the login page followed by the consent page is displayed: 

Picture Picture

After giving the consent, the user will be redirected with the authorization code to the redirect_urispecified.

Following the example, this will be the url:

https://redirecturlapp.com/?code=3049C9C9A5A36FL5199E0DB45EA40084E943EA6AC5A8FD2B6EF0F2ED28B52487&scope=employee.employment%20employee.employment.read%20employee.info%20employee.info.read%20employee.payment%20employee.payment.read%20company.info%20company.info.read%20company.payrollsettings.read%20offline_access&state=9693F36D-9882-4365-A325-36D658B68392

2. Exchange code for the access token

Using the authorization code obtained previously, you can request an access_token using the token URL.

You will need to do a POST request with Basic authentication 

basicAuthorization           Use the client_id and client_secret (both URL-encoded, RFC6749)                                                                          separated by a semicolon "{{client_id}}:{{client_secret}}" base64 encoded

code                         Authorization code received in the previous step

POST /connect/token HTTP/1.1
Host: identityservice.nmbrs.com
Authorization: Basic {{basicAuthorization}} 
Content-Type: application/x-www-form-urlencoded 

grant_type=authorization_code
&code={{code}}
&redirect_uri={{redirect_uri}}

You will receive as a response the access_token, as well as the refresh_token (if the offline_access scope was requested).

The response will look like this:

{
    "access_token": {{access_token}},
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": {{refresh_token}},
    "scope": {{scopes}}
}

3. Refresh the access token

The access_token is short lived. Use the refresh_token received in the previous step to get a new access token and refresh token.

POST /connect/token HTTP/1.1
Host: identityservice.nmbrs.com
Authorization: Basic {{basicAuthorization}}
Content-Type: application/x-www-form-urlencoded

refresh_token={{refresh_token}}
&grant_type=refresh_token

4. Call the API

Make calls against the Nmbrs REST API by simply adding the two following mandatory headers to your request:

access_token                     Retrieved in step 2 or 3

subscription_key             Generated after subscribing to a product in the developer portal

GET /api/companies/{{companyId}}/hourcodes?pageNumber=1&pageSize=20 HTTP/1.1
Host: api.nmbrsapp.com
Authorization: "Bearer " + {{access_token}} 
X-Subscription-Key: {{subscription_key}}            
Accept: application/json