Skip to main content

What do I need to use it?

To get started with the nOps API, you’ll need a few key things:

  1. API Key: First, you’ll need an API key from nOps to authenticate your requests. This key uniquely identifies you and grants secure access to the API. Make sure to keep it private, as it serves as your password for accessing the data.

  2. API Client: You’ll need a tool to make requests to the API, such as Postman or curl. Postman is a popular choice for visualizing and testing API requests, while curl is a command-line tool that allows you to quickly make API requests from a terminal.

  3. Basic Knowledge of RESTful APIs: nOps uses a RESTful API structure, so some familiarity with HTTP methods (e.g., GET for reading data) and endpoints will be helpful for understanding and navigating the available API calls.

How do I create an API key?​

You must generate an API Key to make requests.

Summary of steps

To create a signed request, follow these steps:

  1. Create an API Key in nOps: Obtain an API key by configuring it in the nOps app, which will be used to authenticate your requests.

  2. (Optional) Create a Signature Public/Private Key Pair: For enhanced security, you can create a public/private key pair. Configuring nOps with your public key allows the system to validate the signature of your requests.

  3. Compose Your Request: Use our available documentation for guidance on composing requests and exploring available API endpoints.

Creating an API Key​

  1. Log into the nOps console and from the Organization Settings pane click the API Key option

  2. Click on Let’s Generate Your API Key

    The Enable Signature Verification is an optional security step that can be left blank.

  3. Click Save. You will see a confirmation dialog that contains your newly generated key.

    Save this because you wont be able to copy it later. Make sure to keep it private, as it serves as your password for accessing the data.

    You now have a fully configured API Client and can use this key when you send a request to nOps.

To send an API request​

When sending an API request, include the encoded signature in the x-nops-signature header for authentication.

https://app.nops.io/<REST_URI>

Example using curl:

curl -X GET https://app.nops.io/c/v3/map-migration/ \
-H "X-Nops-Api-Key: 12345.999abcdefghijzxcvbyyy0"

By including the x-nops-signature header and following this format, you ensure your requests are properly authenticated and directed to the correct endpoint.

Example using Postman:

  1. Open Postman

  2. Click on the + to open a new Request Tab

  3. Enter the URL that you wish to use. Our example is https://app.nops.io/c/v3/map-migration/ It retrieves information of MAP projects.

  4. Now, go on the Authorization tab under the URL, and as Auth Type, choose API Key. Fill the key field with X-Nops-Api-Key and the value field is the generated key you saved earlier. On the "Add to" dropdown, pick "Header".

  5. Now hit Send and you should have your response.

Advanced Security Settings​

Click to view details

Create a Signature Verification Key pair​

The following instructions are for Unix-based OS machines. For Windows platforms/OS we suggest using either OpenSSL or PuTTYgen.

Begin by opening a command window.

  1. Generate a PEM Certificate using the following command:
    $ openssl genpkey -out rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:1024

  2. Extract a public key from the PEM certificate by using the following command.
    $ openssl rsa -in rsakey.pem -pubout > key.pub

  3. Copy this information into your clipboard.

  4. Paste your RSA key into the nOps API Key Signature Verification field when generating the key.

Compose your request​

Once you have the key, you can compose a signature string and sign it and send your request.

Signing your Request​

The format for the signature is:

{client_id}.{date_str}.{url}?api_key={key}

The information for the signature request contains the following:

  • client_id: The Client ID is contained in the first part of API_Key that is returned.
    In this example key: api_key=123.aaaa4432454ccccb5a2280e755fdzzzz
    the api_key is 123
  • date_str: Use the yyyy-MM-dd format, such as 2022-11-07
  • url: Use a request url that does not include the domain name. Ensure that the url contains a trailing slash (/) or the signature will not be verified, and your request will fail. The signature must match exactly before it can be verified.
  • API key: Use the format ?api_key=xxx

For example:

123.2022-01-10./nops_api/v1/billingGetTotal/?api_key=123.aaaa4432454ccccb5a2280e755fdzzzz

The example signature shown above can only be used:

on the date: 2022-01-10
for the API URL of: /nops_api/v1/billingGetTotal/
for the client (123) indicated within the api_key request:
?api_key=123.aaaa4432454ccccb5a2280e755fdzzzz

The signature must match exactly for the signature to be verified.

To sign and encode your signature string using your private key.

Following is an example of how to create a key pair using Python instead of the prior instructions to create a key pair. However, in order to use the Python script you may first need to install pycryptodomex by using this command:

pip install pycryptodomex

See: https://pycryptodome.readthedocs.io/en/latest/src/installation.html

import binascii
from Cryptodome.Hash import SHA256
from Cryptodome.PublicKey import RSA
from Cryptodome.Signature import pkcs1_15

key = RSA.generate(1024)
encrypt_key = key.export_key(pkcs=8)
public_key = key.publickey().export_key().decode()

message = "123.2022-01-10./nops_api/v1/billingGetTotal/?api_key=123.aaaa4432454ccccb5a2280e755fdzzzz"
encoded_string = message.encode()
byte_array= bytearray(encoded_string)
sha_bytes = SHA256.new(byte_array)
signature = pkcs1_15.new(encrypt_key).sign(sha_bytes)
signature = binascii.b2a_base64(signature)[:-1].decode("utf-8")