Skip to main content

Welcome to the nullplatform API!

This guide provides an overview of our platform and detailed instructions on how to use the nullplatform API effectively. 🚀

Nullplatform OpenAPI specification​

The nullplatform API is built using the OpenAPI 3.0 specification. You can find the full API documentation in our OpenAPI specs:

Key entities​

When working with the API, you'll interact with the following entities:

+--------------+
| Organization |  (e.g., "Crypto Inc.") - One per company.
+--------------+
  |   +---------+
  |___| Account |  (e.g., "Crypto Kong") - An organization can have multiple accounts.
      +---------+
         |   +-----------+
         |___| Namespace |  (e.g., "Billing", "Fraud") - Each account has multiple namespaces.
             +-----------+
                  |   +-------------+
                  |___| Application |  (e.g., "Payments API") - Multiple per namespace.
                      +-------------+
                            |   +-------+
                            |___| Scope |  (e.g., "Production", "EU") - One or more per application.
                                +-------+

Authentication and access tokens​

Our API requests require an access token, provided in the Authorization header:

Authorization: Bearer <your-access-token>

How do I get an access token?​

Getting an access token is simple and depends on the type of user making the calls:

  • For human users: Use your personal access token, the same one used by our UI. You can retrieve it using our Chrome extension.

  • For machine users: Obtain an access token via an API key. See the API keys docs for details.

Our own Chrome extension 😎

We developed a browser extension that makes it easier to get your personal access token and make calls to our API. You can download the extension from our GitHub repository.

Listing entities, filtering and sorting data​

You can retrieve entity lists by making requests without specifying an ID (e.g., GET /account). Here are some key points:

  • Filtering: Use query parameters, e.g., GET /account?status=active. We support filtering by multiple values using comma as a separator like GET /account?name=crypto-kong&status=active

  • Sorting: Use the sort parameter with the field and order, e.g. GET /account?sort=name:desc. Available sorts are asc and desc.

  • Paging: Use limit and offset parameters to navigate through paginated results.

    • offset indicates where to start in the result set (default is 0).
    • limit specifies the number of results per page (default is 50 and cannot exceed 200).
    • total the number of results that match your query.

  • Specify the parent entity: You are authorized only to list things that you have access to, so you have to filter by the parent entity. For example, if you are searching for applications, specify under which namespace_id you'll be running the query (e.g., GET /application?namespace_id=1234).

  • Searching within multiple parents: You can specify multiple parent entities for the search (up to 10). Ensure you have listing permissions for each parent; otherwise, you will be unauthorized.

  • Responses: All entities will have a uniform response format for list requests. Here's an example:

    GET /application?namespace_id=1234
    {
      "paging": {
        "total": 30,
        "offset": 0,
        "limit": 200
      },
      "results": [
        {
          "id": 1111,
          "name": "Billing API",
          "slug": "billing-api",
          "namespace_id": 1234,
          "status": "active",
          "repository_url": "https://example.com/crypto-inc/accounting-billing-api",
          "repository_app_path": null,
          "is_mono_repo": false,
          "auto_deploy_on_creation": false,
          "template_id": 3456,
          "metadata":  {}
        },
        {
          "id": 1112,
          "name": "Checkout API",
          "slug": "checkout-api",
          "namespace_id": 1234,
          "status": "active",
          "repository_url": "https://example.com/crypto-inc/accounting-checkout-api",
          "repository_app_path": null,
          "is_mono_repo": false,
          "auto_deploy_on_creation": false,
          "template_id": 3456,
          "metadata": {}
        }
      ]
    }

Technical conventions​

Use the right domain​

Note that our API is hosted at https://api.nullplatform.com. We do not use the .io domain for the API.

PUT vs. PATCH​

  • Use PATCH to update specific fields.
  • Use PUT to replace the entire resource.
Be cautious when using PUT

Using PUT on NRN API fully replaces the NRN content. We recommend using PATCH unless you're really sure of what you're doing.

Permissions and access control​

Nullplatform has a permission system that allows for granular access control. The following sections explain how permissions work and how they apply to resources.

API endpoints represent actions​

Each API endpoint corresponds to an action, except for public endpoints. To call an endpoint, you must have permission for the associated action. Some endpoints may also require permissions for additional actions.

Roles define what users can do​

In nullplatform, every user has one or more roles (e.g., developer, admin). Roles determine what actions a user can perform. For instance, assigning the developer role provides permissions to create applications or deploy code.

Access is granted to specific resources​

You need to have access granted for specific resources. For example, being a developer in an experimental application is different from being a developer in a critical application. Therefore, the same role might be granted in one area of the organization but not in another. Your ability to perform actions depends on having a role linked to a specific resource.

You need to get granted access to resources​

Being a developer in a test application doesn't automatically grant the same permissions in a production application. A role needs to be explicitly granted for each resource where access is required.

Permissions are extended to child resources​

Permissions inherit down the hierarchy. If you have the developer role at the account level, you inherit permissions for all namespaces, applications, and scopes within that account. You don't need to request access for each sub-resource.

Putting it all together
  • Action: Defines what you can do in nullplatform (e.g., deploy:create).
  • Role: Links a group of users (e.g., developer) to the actions required for that role (e.g.,organization:read).
  • Resources: The specific part of the organization's assets that a user is granted access to (e.g., "application 8" or "application 4").

How do I grant access to a resource?​

Check our authentication docs for instructions on how to POST new grants.