Skip to content

Service Account & Roles

Service accounts enable software-based authentication against the REST API.
They represent a dedicated identity without assigned roles by default.
Authentication is performed using a public/private key pair.

Create a Key Pair

Use the following commands on a Linux system:

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  • The public key must be uploaded to the service account.
  • The private key must remain securely stored on your side.

Create a Service Account

Frontend:
1. Navigate to Service Accounts
2. Click the "+" button
3. Enter a Name and Description
4. Open the created account via the Actions column
5. Add a key pair: Upload your own public key or download a generated key pair.

API:
Create Service Account: 

POST /service_accounts/{organization_id}

{
"identity": "string",
"account_id": "string"
}

Store both values for later use.

Attach Public Key to service account: 

POST /service_accounts/{organization_id}/{account_id}/keys

Authentication

To authenticate, create a JWT signed with your private key. 

{
"org": "{organization_id}@organizations.vwd",
"acc": "{account_id}@service-accounts.vwd",
"key": "{key_id}@keys.vwd",
"iat": current_timestamp,
"exp": current_timestamp+3600
}

You must send the signed JWT to the following endpoint: 

POST /service_accounts/:authenticateServiceAccount

The endpoint will yield an auth_token that you can use as a Bearer Token to authenticate against our API.

Best Practice:
Avoid authenticating before every API request. This is an antipattern that causes unnecessary latency, increased backend load & degraded performance.

Recommended Approach:
- Cache the auth_token
- Reuse it across requests
- Refresh only when nearing expiration

Assign Roles

Roles can be assigned to service accounts.
To perform API calls within the scope of your organization you can add temporary roles your service account. 

POST /roles/organization/{organization_id}/{identity}/:grantTemporaryRoles

Hint: Your user identity needs to be Organization Admin. In the frontend, go to the “Roles” section and check whether the “Organization Admin” role has been assigned to your identity. If not, assign it using the “+” button