BlocktionBlocktion Docs
Platform•GitHub

Documentation

Getting Started
Parameters & Configuration
Authentication
Workflows
Blocks
Handlers
Sessions
Providers
DataStores
Triggers
Marketplace

Authentication

Secure your API with OAuth2 password flow, JWT tokens, and role-based access control

Overview

The Blocktion API uses OAuth2 password flow for authentication. All API endpoints (except public ones) require a valid access token in the Authorization header.

Key Concepts

  • • Email as Primary Identifier
  • • JWT Tokens with 30-minute expiration
  • • Role-Based Access Control (RBAC)
  • • Development Mode for advanced users

Authentication Flow

  1. 1. Register a new user account
  2. 2. Login with email and password
  3. 3. Use token in Authorization header
  4. 4. Refresh token when it expires

Endpoints

POST/api/auth/login

Login

Obtain an access token using OAuth2 Password flow (form fields)

Request Body

{
  "username": "string (required, your email)",
  "password": "string (required)"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": "user_123456",
    "username": "johndoe",
    "email": "user@example.com",
    "full_name": "John Doe",
    "roles": [
      "user"
    ],
    "permissions": [],
    "has_dev_mode": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/auth/login" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=string%20(required%2C%20your%20email)&password=string%20(required)"
POST/api/auth/register

Register

Create a new user account

Request Body

{
  "email": "string (required)",
  "password": "string (required, min 8 chars)",
  "username": "string (optional)",
  "full_name": "string (optional)",
  "roles": "array (optional, defaults to ['user'])"
}

Response

{
  "id": "user_123456",
  "username": "johndoe",
  "email": "user@example.com",
  "full_name": "John Doe",
  "disabled": false,
  "roles": [
    "user"
  ],
  "permissions": [],
  "has_dev_mode": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

cURL Example

curl -X POST "https://api.blocktion.io/api/auth/register" \
+  -H "Content-Type: application/json" \
+  -d '{
  "email": "string (required)",
  "password": "string (required, min 8 chars)",
  "username": "string (optional)",
  "full_name": "string (optional)",
  "roles": "array (optional, defaults to ['user'])"
}'
GET/api/auth/me

Get Current User

Get information about the currently authenticated user

Response

{
  "id": "user_123456",
  "username": "johndoe",
  "email": "user@example.com",
  "full_name": "John Doe",
  "disabled": false,
  "roles": [
    "user"
  ],
  "permissions": [],
  "has_dev_mode": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

cURL Example

curl -X GET "https://api.blocktion.io/api/auth/me" \
+  -H "Authorization: Bearer <your_access_token>"
GET/api/auth/usersAdmin Only

List Users

Get all users (admin only)

Response

[
  {
    "id": "user_123456",
    "username": "johndoe",
    "email": "user@example.com",
    "full_name": "John Doe",
    "disabled": false,
    "roles": [
      "user"
    ],
    "permissions": [],
    "has_dev_mode": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

cURL Example

curl -X GET "https://api.blocktion.io/api/auth/users" \
+  -H "Authorization: Bearer <your_access_token>"
GET/api/auth/users/{user_id}

Get User by ID

Get a specific user (self or admin)

Response

{
  "id": "user_123456",
  "username": "johndoe",
  "email": "user@example.com",
  "full_name": "John Doe",
  "disabled": false,
  "roles": [
    "user"
  ],
  "permissions": [],
  "has_dev_mode": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

cURL Example

curl -X GET "https://api.blocktion.io/api/auth/users/{user_id}" \
+  -H "Authorization: Bearer <your_access_token>"
PUT/api/auth/users/{user_id}

Update User

Update a user (self or admin; roles/permissions require admin)

Request Body

{
  "email": "string (optional)",
  "password": "string (optional, min 8 chars)",
  "username": "string (optional)",
  "full_name": "string (optional)",
  "disabled": "boolean (optional)",
  "roles": "string[] (optional, admin only)",
  "permissions": "string[] (optional, admin only)",
  "has_dev_mode": "boolean (optional)"
}

Response

{
  "id": "user_123456",
  "username": "johndoe",
  "email": "user@example.com",
  "full_name": "John Doe",
  "disabled": false,
  "roles": [
    "user"
  ],
  "permissions": [],
  "has_dev_mode": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

cURL Example

curl -X PUT "https://api.blocktion.io/api/auth/users/{user_id}" \
+  -H "Authorization: Bearer <your_access_token>"
DELETE/api/auth/users/{user_id}Admin Only

Delete User

Delete a user (admin only)

Response

{
  "message": "User deleted successfully"
}

cURL Example

curl -X DELETE "https://api.blocktion.io/api/auth/users/{user_id}" \
+  -H "Authorization: Bearer <your_access_token>"
POST/api/auth/dev-mode/activate

Activate Dev Mode

Enable dev mode for current user

Response

{
  "id": "user_123456",
  "email": "user@example.com",
  "has_dev_mode": true
}

cURL Example

curl -X POST "https://api.blocktion.io/api/auth/dev-mode/activate" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your_access_token>" \
+  -d 'undefined'
POST/api/auth/dev-mode/deactivate

Deactivate Dev Mode

Disable dev mode for current user

Response

{
  "id": "user_123456",
  "email": "user@example.com",
  "has_dev_mode": false
}

cURL Example

curl -X POST "https://api.blocktion.io/api/auth/dev-mode/deactivate" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your_access_token>" \
+  -d 'undefined'

Error Responses

Common HTTP status codes and their meanings for authentication endpoints

400

Bad Request

Invalid request data or missing required fields

401

Unauthorized

Authentication required or invalid credentials

403

Forbidden

Insufficient permissions for this action

409

Conflict

User already exists or email is already registered

422

Unprocessable Entity

Validation errors in request data

500

Internal Server Error

Server error occurred

Security Notes

Important security considerations when using the authentication API

Token Security

Store access tokens securely and never expose them in client-side code or logs.

HTTPS Only

Always use HTTPS in production to protect credentials and tokens in transit.

Token Refresh

Implement proper token refresh logic to handle token expiration gracefully.