Create an Organisation

This tutorial explains how you create an organisation, how to view its members and how to create an API key for further API access.

If you prefer importing this tutorial into Postman or Insomnia, download the har archive file and import into your preferred tool.

Prerequisites

You must have a registered user account in Arratech and a valid access token. If not, visit the Getting Started tutorial for how to do it.

Step 1. Create an Organisation

Until your user becomes a member of an organization your permission to perform API operations are limited.

An organization is a customer of Arratech and an entity that has users in Arratech's Portal. Additionally, an organization has one or many Access Points and/or SMP services associated with it. An organization in this context is not an end user (typically called Corner 1 or Corner 4).

As a new user you have the option of either creating a new organization or to join an existing organisation. If you create an organization You automatically become the administrator of it.

Below we show how you create a new organisation with the /orgs endpoint.

curl -X POST https://api.arratech.com/orgs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legalIdentifier": "123456789",
    "legalName": "Your Company AB",
    "countryCode": "SE",
    "legalIdentifierCode": "SE:ORGNR"
  }'

The response contains your new organisation, including its id. Take note of it since you will need it in step 3. Below is a sample response on how it can look and what to take note of.

Step 2. Verify Organisation

You can now verify that you have access to the created organisation by calling the /orgs/{orgId} endpoint to verify that your new organisation is returned.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

In the above response you will find the key value pair "sharedModeEnabled": true. When you create your first organization we set the value to true so that you are restricted to use Arratech's shared Access Point/SMP until we enable your organization for use of the White Labeled services for Access Point and SMP. The latter requires you to be an OpenPeppol Service Provider member.

Step 3. List Organisation Members

The user that creates an organization automatically becomes the admin of that organization.

To verify it you can call the /orgs/:orgId/members endpoint replacing YOURORGS_ID with the organisation id from the previous step.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/members \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 4. Verify User is a Member

Verify that your user is a member in the returned members list. You can also verify this by requesting your own user and inspect the memberships property.

curl -X GET https://api.arratech.com/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 5. Create API Key

Now, as an administrator member of the new organisation you are able to create API Keys for this organisation. API keys makes it easier to access the API for machine to machine integrations, and also more convenient for end users compared to using access tokens (with security implications so use with care). More information, including how API keys are used is described in the API documentation.

To create an API key we use the /orgs/:orgId/api_keys endpoint.

curl -X POST https://api.arratech.com/orgs/YOUR_ORGS_ID/api_keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first API Key",
    "description": "API key for accessing production services",
    "expires": "2025-12-31T23:59:59Z",
	"isActive": true,
	"role": "orgadmin"
  }'

The unhashed API key value is just returned once so make sure you save it in a secure location for further use.