Server + API: Application Implementation

In this section of the tutorial, we will take an in-depth look into our API and its associated Non Interactive Client.

For simplicity reasons we will keep our implementation solely focused on the authentication and authorization part. As you will see in the samples the input timesheet entry will be hard-coded and the API will not persist the timesheet entry, simply echo back some of the info.

Define the API endpoints

First we need to define the endpoints of our API.

What is an API endpoint?

An API endpoint is a unique URL that represents an object. In order to interact with this object you need to point your client towards that URL. For example, if you had an API that could return either order or customers, you might configure two endpoints: /orders and /customers. Your client would interact with these endpoints using different HTTP methods, for example POST /orders to create a new order, or GET /orders to retrieve the dataset of one or more orders.

We will configure one single endpoint that will be used for creating timesheet entries. The endpoint will be /timesheets/upload and the HTTP method POST.

The API will expect a JSON object as input, containing the timesheet information. We will use the following JSON:

{
  'user_id': '007',
  'date': '2017-05-10T17:40:20.095Z',
  'project': 'StoreZero',
  'hours': 5
}

The API will print the JSON, so we can verify the contents and echo back a message like the following: Created timesheet 14 for employee 007.

See the implementation in Node.js

Secure the API endpoints

Configure the API

In order to secure your endpoints you need to have your API configured in the Auth0 Dashboard. For information on how to do that refer to the Configure the API paragraph of this document.

The first step towards securing our API endpoint is to get an access token as part of the Header and validate it. If it's not valid then we should return an HTTP Status 401 (Unauthorized) to the calling process.

See the implementation in Node.js

Get an Access Token

To get an access token without using our Client sample implementation, perform a POST operation to the https://YOUR_AUTH0_DOMAIN/oauth/token endpoint with a payload in the following format:

{
  audience: "YOUR_API_IDENTIFIER",
  grant_type: "client_credentials",
  client_id: "",
  client_secret: ""
}

Check the Client permissions

Now we have secured our API's endpoint with an access token but we still haven't ensured that the process calling the API has indeed the rights to post a new timesheet entry.

As discussed earlier in this doc, each access token may include a list of the permissions that have been granted to the client. These permissions are defined using the scope request parameter. For more information on how to configure this refer to the Configure the Scopes paragraph.

For our endpoint we will require the scope batch:upload.

See the implementation in Node.js

Implement the Non Interactive Client

In this section we will see how we can implement a Non Interactive Client for our scenario.

For simplicity reasons we will keep our implementations solely focused on the authentication and authorization part and configure our client to send a single hard-coded timesheet entry to the API. Also, we will print in the console, something we wouldn't do with a server running process.

Get an Access Token

We will start by invoking the Auth0 /oauth/token API endpoint in order to get an access token.

In order to do so we will need the following configuration values:

  • Domain: The value of your Auth0 Domain. You can retrieve it from the Settings of your Client at the Auth0 Dashboard. This value will be a part of the API URL: https://YOUR_AUTH0_DOMAIN/oauth/token.

  • Audience: The value of your API Identifier. You can retrieve it from the Settings of your API at the Auth0 Dashboard.

  • Client Id: The value of your Auth0 Client's Id. You can retrieve it from the Settings of your Client at the Auth0 Dashboard.

  • Client Secret: The value of your Auth0 Client's Secret. You can retrieve it from the Settings of your Client at the Auth0 Dashboard.

Our implementation should perform a POST operation to the https://YOUR_AUTH0_DOMAIN/oauth/token endpoint with a payload in the following format:

{
  "audience": "YOUR_API_IDENTIFIER",
  "grant_type": "client_credentials",
  "client_id": "",
  "client_secret": ""
}

For more information on this refer to: API Authorization: Asking for Access Tokens for a Client Credentials Grant.

See the implementation in Python.

Invoke the API

Now that we have an access token, which includes the valid scopes, we can invoke our API.

In order to do so we will:

  • Build a hard-coded timesheet entry in JSON format.
  • Add the access token as an Authorization header to our request.
  • Make the HTTP POST request.
  • Parse the response and print it in the terminal (optional).

See the implementation in Python.

Previous Tutorial
2. Auth0 Configuration
Next Tutorial
Conclusion