Application Implementation (Server Apps + API)

In this section of the tutorial, we will take an in-depth look into our API and its associated Machine-to-Machine Application. To start at the beginning, read Server Applications with API.

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

Define the API endpoints

An API endpoint is a static URI that represents a resource (collection of data).

For example, a restaurant API might have endpoints such as /orders and /customers. An application that connects to this API can perform CRUD (create, read, update, delete) operations by calling an API endpoint with the associated HTTP method (POST, GET, PUT, PATCH, or DELETE).

For ExampleCo’s Timesheets API, you will need to configure an endpoint to create timesheet entries.

HTTP method	API endpoint	Description
POST	/timesheets/upload	Creates a new timesheet entry

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

If the API processes the request successfully, it sends a response with an HTTP 201 Created status code and the body containing a JSON object with a message property that describes the newly-created timesheet:

{
"message": "Created timesheet 14 for employee 007."
}

See the implementation in Node.js.

Secure the API endpoints

To secure your API endpoint(s), you need to implement a middleware function within your API application to handle tokens. This function checks if a token was included with the API request, validates the token, and then confirms if the scope(s) required to perform the requested action are present.

If all criteria are satisfied, the API application responds with the message mentioned previously. If there are any issues with the provided access token (or it’s not provided at all), the API application sends a response with the HTTP 401 Unauthorized status code.

See the implementation inNode.js.

Get an access token

To get an access token without using our application sample implementation, call the Auth0 Authentication API’s Get Token endpoint with the following payload:

{
  audience: "{yourApiIdentifier}",
  grant_type: "client_credentials",
  client_id: "${account.client_id}",
  client_secret: "${account.client_secret}"
}

Check the application 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 the rights to post a new timesheet entry.

As discussed earlier, each access token may include a list of the permissions that have been granted to the application. These permissions are defined using the scope request parameter. To learn how to configure this, see the Configure the Scopes paragraph.

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

See the implementation inNode.js.

Implement the Machine-to-Machine Application

In this section, we will see how we can implement a Machine-to-Machine Application for our scenario.

Get an access token

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

To do so, we will need the following configuration values you can find in your application settings:

• Domain: Auth0 Domain and also your tenant identifier. This value will be a part of the API URL: https://{yourTenant}/oauth/token.
• Audience: API identifier.
• Client ID: Auth0 Application’s Client ID.
• Client Secret: Auth0 application’s Client Secret.

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

{
  "audience": "{yourApiIdentifier}",
  "grant_type": "client_credentials",
  "client_id": "${account.client_id}",
  "client_secret": "${account.client_secret}"
}

To learn more, see Call Your API Using the Client Credentials Flow.

See the implementation inPython.

Invoke the API

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

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 inPython.