Authentication

All MetaKraftwerk REST API endpoints require authentication via a JSON Web Token (JWT). Before calling any API endpoint, you must obtain an access token by authenticating with your credentials.

See Also

• Login/Logout — Web application authentication
• User Management — Managing user accounts and permissions
• Security — Security overview

Overview

The authentication flow follows a standard JWT-based approach:

1. Send your credentials to the authentication endpoint.
2. Receive an access token in the response.
3. Include the token in the Authorization header of all subsequent API requests.

Endpoint

POST https://app.metakraftwerk.com/authentication

Request

Headers

Header	Value
Content-Type	application/json

Body

Field	Type	Required	Description
strategy	string	Yes	Authentication strategy. Use "local" for username/password authentication.
email	string	Yes	The email address associated with your MetaKraftwerk user account.
password	string	Yes	The password for your MetaKraftwerk user account.

{
  "strategy": "local",
  "email": "your.email@example.com",
  "password": "your-password"
}

Response

Success — 201 Created

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9...",
  "authentication": {
    "strategy": "local",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9..."
  },
  "user": {
    "id": 1,
    "email": "your.email@example.com"
  }
}

Field	Type	Description
accessToken	string	The JWT to use in subsequent API requests.
authentication	object	Authentication details including the strategy used.
user	object	Basic information about the authenticated user.

Error Responses

Status	Condition	Example Message
401	Invalid credentials	Invalid login
400	Missing required fields	'email' is required

Using the Access Token

Once obtained, include the access token in the Authorization header of every API request using the Bearer scheme:

Authorization: Bearer <ACCESS_TOKEN>

Token Expiration

JWTs have a limited lifetime. When your token expires, the API returns a 401 Not authenticated error. You must re-authenticate to obtain a new token.

Examples

cURL

# Authenticate and extract the access token
ACCESS_TOKEN=$(curl -s -X POST "https://app.metakraftwerk.com/authentication" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "local",
    "email": "your.email@example.com",
    "password": "your-password"
  }' | jq -r '.accessToken')

# Use the token in subsequent requests
curl -X GET "https://app.metakraftwerk.com/api/v1/projects" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

// Authenticate
const authResponse = await fetch('https://app.metakraftwerk.com/authentication', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    strategy: 'local',
    email: 'your.email@example.com',
    password: 'your-password'
  })
});

const { accessToken } = await authResponse.json();

// Use the token in subsequent requests
const response = await fetch('https://app.metakraftwerk.com/api/v1/projects', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const projects = await response.json();

Permissions

API access is governed by user-level and project-level permissions. Even with a valid token, requests may be rejected if the user lacks the required permissions for the target resource. Common permission requirements include:

Permission	Required For
Project access	Accessing any project-scoped resource
write_instances	Creating or updating instances
read_builds	Downloading build results
write_builds	Starting new builds

INFO

Permissions are assigned per project by an administrator. Contact your MetaKraftwerk administrator if you need additional access.