DICTRA Auth Service API

API Endpoint

https://api.dictra.com.br

Version: 1.0.0 Base URL: https://api.dictra.com.br

The DICTRA Auth Service provides authentication, authorization, and user management capabilities for the DICTRA PIX payment platform. This service implements LSO/RSO (First and Second Signature) dual approval workflow for sensitive operations.

Features

JWT-based authentication with access and refresh tokens
User and entity management with encrypted PII
Permission-based authorization with bitmap storage
LSO/RSO dual approval workflow for critical operations
Comprehensive audit logging
Active Directory integration support

Authentication

Most endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <access_token>

Public endpoints (login, refresh) do not require authentication.

Error Codes

Code	HTTP Status	Description
AUTH001	401	Invalid credentials
AUTH002	403	Account is locked
AUTH003	403	Account is inactive
AUTH004	403	Account pending approval
AUTH005	403	Entity is inactive
AUTH010	401	Session expired or revoked
AUTH011	401	Session inactive due to timeout
AUTH020	400	Current password is incorrect
AUTH021	400	New password does not meet requirements
AUTH022	400	Password was recently used
USER001	409	Login already exists
USER002	409	Email already exists
USER003	400	Password does not meet requirements
USER004	400	Entity is inactive
ENTITY001	409	Entity code already exists
ENTITY002	400	Consolidation entity is inactive
GROUP001	409	Group code already exists in entity
GROUP002	400	Entity is inactive
GROUP003	409	Group has active users
APPROVAL001	409	Operation has expired
APPROVAL002	409	Operation is not in a valid state for LSO approval
APPROVAL003	409	Cannot approve your own request
APPROVAL004	409	RSO must be different from LSO approver
APPROVAL005	409	Operation is not in a valid state for rejection

Health & Status ¶

Health Check ¶

GET https://api.dictra.com.br/health

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    }
  },
  "required": [
    "status"
  ]
}

Health Check
GET`/health`

Liveness probe endpoint. Returns 200 if service is running.

Readiness Check ¶

GET https://api.dictra.com.br/ready

Responses200503

Headers

Content-Type: application/json

Body

{
  "status": "ready",
  "database": "connected"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "database": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "database"
  ]
}

Headers

Content-Type: application/json

Body

{
  "status": "not ready",
  "database": "disconnected"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "database": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "database"
  ]
}

Readiness Check
GET`/ready`

Readiness probe endpoint. Returns 200 if service is ready (database connected).

Authentication ¶

POST https://api.dictra.com.br/api/v1/auth/login

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "login": "admin",
  "password": "Admin@2026!"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "login": {
      "type": "string",
      "description": "User login"
    },
    "password": {
      "type": "string",
      "description": "User password"
    }
  },
  "required": [
    "login",
    "password"
  ]
}

Responses200401403

Headers

Content-Type: application/json

Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entity_id": "550e8400-e29b-41d4-a716-446655440001",
    "group_id": "550e8400-e29b-41d4-a716-446655440002",
    "login": "admin",
    "name": "System Administrator",
    "email": "admin@dictra.com.br",
    "status": "ACTIVE",
    "is_admin": true,
    "last_login_at": "2026-01-24T10:30:00Z"
  },
  "must_change_password": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "JWT access token"
    },
    "refresh_token": {
      "type": "string",
      "description": "JWT refresh token"
    },
    "expires_in": {
      "type": "number",
      "description": "Token expiration in seconds"
    },
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "User UUID"
        },
        "entity_id": {
          "type": "string",
          "description": "Entity UUID"
        },
        "group_id": {
          "type": "string",
          "description": "Group UUID"
        },
        "login": {
          "type": "string",
          "description": "User login"
        },
        "name": {
          "type": "string",
          "description": "User full name"
        },
        "email": {
          "type": "string",
          "description": "User email"
        },
        "status": {
          "type": "string",
          "enum": [
            "ACTIVE",
            "INACTIVE",
            "PENDING_APPROVAL",
            "LOCKED",
            "SUSPENDED"
          ],
          "description": "User status"
        },
        "is_admin": {
          "type": "boolean",
          "description": "Whether user is admin"
        },
        "last_login_at": {
          "type": "string",
          "description": "Last login timestamp"
        }
      },
      "required": [
        "id",
        "entity_id",
        "group_id",
        "login",
        "name",
        "email",
        "status",
        "is_admin"
      ],
      "description": "User information"
    },
    "must_change_password": {
      "type": "boolean",
      "description": "Password change required"
    }
  },
  "required": [
    "token",
    "refresh_token",
    "expires_in",
    "user"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Invalid credentials",
  "code": "AUTH001"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error",
    "code"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Account is locked",
  "code": "AUTH002"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error",
    "code"
  ]
}

Refresh Token ¶

POST https://api.dictra.com.br/api/v1/auth/refresh

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "refresh_token": {
      "type": "string",
      "description": "Refresh token"
    }
  },
  "required": [
    "refresh_token"
  ]
}

Responses200401

Headers

Content-Type: application/json

Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "New JWT access token"
    },
    "refresh_token": {
      "type": "string",
      "description": "New JWT refresh token"
    },
    "expires_in": {
      "type": "number",
      "description": "Token expiration in seconds"
    }
  },
  "required": [
    "token",
    "refresh_token",
    "expires_in"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Session expired or revoked",
  "code": "AUTH010"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error",
    "code"
  ]
}

Refresh Token
POST`/api/v1/auth/refresh`

Refresh an access token using a refresh token.

Logout ¶

POST https://api.dictra.com.br/api/v1/auth/logout

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses204401

This response has no content.

Headers

Content-Type: application/json

Body

{
  "error": "Invalid credentials",
  "code": "AUTH001"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error"
  ]
}

Logout
POST`/api/v1/auth/logout`

Revoke the current session.

Get Current User ¶

GET https://api.dictra.com.br/api/v1/auth/me

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_id": "550e8400-e29b-41d4-a716-446655440001",
  "group_id": "550e8400-e29b-41d4-a716-446655440002",
  "login": "admin",
  "name": "System Administrator",
  "email": "admin@dictra.com.br",
  "status": "ACTIVE",
  "is_admin": true,
  "permissions": [
    1
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "entity_id": {
      "type": "string"
    },
    "group_id": {
      "type": "string"
    },
    "login": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "is_admin": {
      "type": "boolean"
    },
    "permissions": {
      "type": "array"
    }
  },
  "required": [
    "id",
    "entity_id",
    "group_id",
    "login",
    "name",
    "email",
    "status",
    "is_admin",
    "permissions"
  ]
}

Get Current User
GET`/api/v1/auth/me`

Get information about the currently authenticated user.

Change Password ¶

POST https://api.dictra.com.br/api/v1/auth/change-password

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "current_password": "OldPassword@2026!",
  "new_password": "NewPassword@2026!"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "current_password": {
      "type": "string",
      "description": "Current password"
    },
    "new_password": {
      "type": "string",
      "description": "New password (min 12 chars)"
    }
  },
  "required": [
    "current_password",
    "new_password"
  ]
}

Responses200400

Headers

Content-Type: application/json

Body

{
  "message": "password changed successfully"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    }
  },
  "required": [
    "message"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Current password is incorrect",
  "code": "AUTH020"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error",
    "code"
  ]
}

Change Password
POST`/api/v1/auth/change-password`

Change the current user’s password.

Users ¶

List Users ¶

GET https://api.dictra.com.br/api/v1/users?page=1&page_size=20&search=john&status=ACTIVE&group_id=550e8400-e29b-41d4-a716-446655440000&entity_id=550e8400-e29b-41d4-a716-446655440001

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_id": "550e8400-e29b-41d4-a716-446655440001",
      "group_id": "550e8400-e29b-41d4-a716-446655440002",
      "login": "admin",
      "name": "System Administrator",
      "email": "admin@dictra.com.br",
      "status": "ACTIVE",
      "is_admin": true,
      "last_login_at": "2026-01-24T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 100,
    "total_pages": 5
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "User list"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "page": {
          "type": "number"
        },
        "page_size": {
          "type": "number"
        },
        "total_count": {
          "type": "number"
        },
        "total_pages": {
          "type": "number"
        }
      },
      "required": [
        "page",
        "page_size",
        "total_count",
        "total_pages"
      ]
    }
  },
  "required": [
    "data",
    "pagination"
  ]
}

List Users
GET`/api/v1/users{?page,page_size,search,status,group_id,entity_id}`

List users with pagination and filters. Non-admin users can only see users in their entity.

URI Parameters

HideShow

page

number (optional) Example: 1

Page number (default: 1)

page_size

number (optional) Example: 20

Items per page (max: 100, default: 20)

search

string (optional) Example: john

Search in login, name, email

status

string (optional) Example: ACTIVE

Filter by status

Choices: ACTIVE INACTIVE PENDING_APPROVAL LOCKED SUSPENDED

group_id

string (optional) Example: 550e8400-e29b-41d4-a716-446655440000

Filter by group

entity_id

string (optional) Example: 550e8400-e29b-41d4-a716-446655440001

Filter by entity (admin only)

Get User ¶

GET https://api.dictra.com.br/api/v1/users/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_id": "550e8400-e29b-41d4-a716-446655440001",
  "entity_name": "DICTRA",
  "group_id": "550e8400-e29b-41d4-a716-446655440002",
  "group_name": "System Administrator",
  "login": "admin",
  "name": "System Administrator",
  "email": "admin@dictra.com.br",
  "status": "ACTIVE",
  "is_admin": true,
  "can_approve": true,
  "permissions": [
    1
  ],
  "last_login_at": "2026-01-24T10:30:00Z",
  "created_at": "2026-01-01T00:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "entity_id": {
      "type": "string"
    },
    "entity_name": {
      "type": "string"
    },
    "group_id": {
      "type": "string"
    },
    "group_name": {
      "type": "string"
    },
    "login": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "is_admin": {
      "type": "boolean"
    },
    "can_approve": {
      "type": "boolean"
    },
    "permissions": {
      "type": "array"
    },
    "last_login_at": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "entity_id",
    "entity_name",
    "group_id",
    "group_name",
    "login",
    "name",
    "email",
    "status",
    "is_admin",
    "can_approve",
    "permissions",
    "created_at"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Invalid credentials",
  "code": "AUTH001"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error"
  ]
}

Get User
GET`/api/v1/users/{id}`

Get user details by ID.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
User UUID

Create User ¶

POST https://api.dictra.com.br/api/v1/users

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "entity_id": "550e8400-e29b-41d4-a716-446655440001",
  "group_id": "550e8400-e29b-41d4-a716-446655440002",
  "login": "johndoe",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "password": "SecurePass@2026!",
  "must_change_password": true
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "entity_id": {
      "type": "string",
      "description": "Entity UUID"
    },
    "group_id": {
      "type": "string",
      "description": "Group UUID"
    },
    "login": {
      "type": "string",
      "description": "User login (3-50 chars)"
    },
    "name": {
      "type": "string",
      "description": "Full name (2-200 chars)"
    },
    "email": {
      "type": "string",
      "description": "Email address"
    },
    "password": {
      "type": "string",
      "description": "Password (min 12 chars)"
    },
    "must_change_password": {
      "type": "boolean",
      "description": "Force password change on first login"
    }
  },
  "required": [
    "entity_id",
    "group_id",
    "login",
    "name",
    "email",
    "password"
  ]
}

Responses201409

Headers

Content-Type: application/json

Body

{
  "message": "User creation pending approval",
  "pending_operation_id": "550e8400-e29b-41d4-a716-446655440099",
  "status": "PENDING_LSO",
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "pending_operation_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "user_id": {
      "type": "string"
    }
  },
  "required": [
    "message",
    "pending_operation_id",
    "status",
    "user_id"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Login already exists",
  "code": "USER001"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error",
    "code"
  ]
}

Create User
POST`/api/v1/users`

Create a new user. This operation requires LSO/RSO approval.

Update User ¶

PUT https://api.dictra.com.br/api/v1/users/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "name": "John Doe Updated",
  "email": "john.updated@example.com",
  "group_id": "550e8400-e29b-41d4-a716-446655440003"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Full name"
    },
    "email": {
      "type": "string",
      "description": "Email address"
    },
    "group_id": {
      "type": "string",
      "description": "New group UUID"
    }
  }
}

Responses200404

Headers

Content-Type: application/json

Body

{
  "message": "User update pending approval",
  "pending_operation_id": "550e8400-e29b-41d4-a716-446655440099",
  "status": "PENDING_LSO"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "pending_operation_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  },
  "required": [
    "message",
    "pending_operation_id",
    "status"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "Invalid credentials",
  "code": "AUTH001"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message"
    },
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "details": {
      "type": "object",
      "properties": {},
      "description": "Additional error details"
    }
  },
  "required": [
    "error"
  ]
}

Update User
PUT`/api/v1/users/{id}`

Update user information. This operation requires LSO/RSO approval.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
User UUID

Deactivate User ¶

DELETE https://api.dictra.com.br/api/v1/users/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "message": "User deactivation pending approval",
  "pending_operation_id": "550e8400-e29b-41d4-a716-446655440099",
  "status": "PENDING_LSO"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "pending_operation_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  },
  "required": [
    "message",
    "pending_operation_id",
    "status"
  ]
}

Deactivate User
DELETE`/api/v1/users/{id}`

Deactivate a user account. This operation requires LSO/RSO approval.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
User UUID

Entities ¶

List Entities ¶

GET https://api.dictra.com.br/api/v1/entities?page=1&page_size=20&search=bank&status=ACTIVE&type=BANK&consolidation_id=550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "DICTRA",
      "name": "DICTRA",
      "legal_name": "DICTRA Tecnologia LTDA",
      "cnpj": "12.345.***/**67-89",
      "ispb": "12345678",
      "type": "BANK",
      "status": "ACTIVE",
      "created_at": "2026-01-24T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 50,
    "total_pages": 3
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "page": {
          "type": "number"
        },
        "page_size": {
          "type": "number"
        },
        "total_count": {
          "type": "number"
        },
        "total_pages": {
          "type": "number"
        }
      },
      "required": [
        "page",
        "page_size",
        "total_count",
        "total_pages"
      ]
    }
  },
  "required": [
    "data",
    "pagination"
  ]
}

List Entities
GET`/api/v1/entities{?page,page_size,search,status,type,consolidation_id}`

List entities with pagination and filters.

URI Parameters

HideShow

page: number (optional) Example: 1
Page number
page_size: number (optional) Example: 20
Items per page (max: 100)
search: string (optional) Example: bank
Search in code, name
status: string (optional) Example: ACTIVE
Filter by status
type: string (optional) Example: BANK
Filter by type
consolidation_id: string (optional) Example: 550e8400-e29b-41d4-a716-446655440000
Filter by consolidation

Get Entity ¶

GET https://api.dictra.com.br/api/v1/entities/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "DICTRA",
  "name": "DICTRA",
  "legal_name": "DICTRA Tecnologia LTDA",
  "cnpj": "12.345.***/**67-89",
  "ispb": "12345678",
  "type": "BANK",
  "status": "ACTIVE",
  "created_at": "2026-01-24T10:30:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Entity UUID"
    },
    "code": {
      "type": "string",
      "description": "Entity code"
    },
    "name": {
      "type": "string",
      "description": "Entity name"
    },
    "legal_name": {
      "type": "string",
      "description": "Legal name"
    },
    "cnpj": {
      "type": "string",
      "description": "Masked CNPJ"
    },
    "ispb": {
      "type": "string",
      "description": "ISPB code"
    },
    "type": {
      "type": "string",
      "enum": [
        "BANK",
        "FINTECH",
        "PSP",
        "BACEN",
        "OTHER"
      ],
      "description": "Entity type"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "PENDING_APPROVAL",
        "SUSPENDED"
      ],
      "description": "Entity status"
    },
    "created_at": {
      "type": "string",
      "description": "Creation timestamp"
    }
  },
  "required": [
    "id",
    "code",
    "name",
    "legal_name",
    "cnpj",
    "type",
    "status",
    "created_at"
  ]
}

Get Entity
GET`/api/v1/entities/{id}`

Get entity details by ID.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
Entity UUID

Create Entity ¶

POST https://api.dictra.com.br/api/v1/entities

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "code": "BANK01",
  "name": "Example Bank",
  "legal_name": "Example Bank S.A.",
  "cnpj": "12345678000190",
  "ispb": "12345678",
  "type": "BANK",
  "consolidation_id": "550e8400-e29b-41d4-a716-446655440000"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Entity code (2-20 chars)"
    },
    "name": {
      "type": "string",
      "description": "Entity name (2-200 chars)"
    },
    "legal_name": {
      "type": "string",
      "description": "Legal name (2-300 chars)"
    },
    "cnpj": {
      "type": "string",
      "description": "CNPJ (14 digits)"
    },
    "ispb": {
      "type": "string",
      "description": "ISPB code (8 digits)"
    },
    "type": {
      "type": "string",
      "enum": [
        "BANK"
      ],
      "description": "Entity type"
    },
    "consolidation_id": {
      "type": "string",
      "description": "Parent entity UUID"
    }
  },
  "required": [
    "code",
    "name",
    "legal_name",
    "cnpj",
    "type"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "message": "Entity creation pending approval",
  "pending_operation_id": "550e8400-e29b-41d4-a716-446655440099",
  "status": "PENDING_LSO",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "pending_operation_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "entity_id": {
      "type": "string"
    }
  },
  "required": [
    "message",
    "pending_operation_id",
    "status",
    "entity_id"
  ]
}

Create Entity
POST`/api/v1/entities`

Create a new entity. This operation requires LSO/RSO approval. Admin only.

Approvals ¶

List Pending Operations ¶

GET https://api.dictra.com.br/api/v1/approvals?page=1&page_size=20&status=PENDING_LSO&operation_type=1&requested_by=550e8400-e29b-41d4-a716-446655440000&target_id=550e8400-e29b-41d4-a716-446655440001&include_expired=false

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_id": "550e8400-e29b-41d4-a716-446655440001",
      "operation_type": 1,
      "operation_type_name": "USER_REGISTRATION",
      "target_table: `dictra_auth.users`": "",
      "target_id": "550e8400-e29b-41d4-a716-446655440002",
      "status": "PENDING_LSO",
      "requested_by": "550e8400-e29b-41d4-a716-446655440003",
      "requested_at": "2026-01-24T10:30:00Z",
      "expires_at": "2026-01-31T10:30:00Z",
      "is_expired": false
    }
  ],
  "pagination": {}
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "pagination": {
      "type": "object",
      "properties": {}
    }
  },
  "required": [
    "data",
    "pagination"
  ]
}

List Pending Operations
GET`/api/v1/approvals{?page,page_size,status,operation_type,requested_by,target_id,include_expired}`

List pending operations requiring approval.

URI Parameters

HideShow

page: number (optional) Example: 1
page_size: number (optional) Example: 20
status: string (optional) Example: PENDING_LSO
operation_type: number (optional) Example: 1
Operation type code
requested_by: string (optional) Example: 550e8400-e29b-41d4-a716-446655440000
target_id: string (optional) Example: 550e8400-e29b-41d4-a716-446655440001
include_expired: boolean (optional) Example: false

Get Pending Operation ¶

GET https://api.dictra.com.br/api/v1/approvals/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": 1,
  "operation_type_name": "USER_REGISTRATION",
  "target_table: `dictra_auth.users`": "Hello, world!",
  "target_id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "PENDING_LSO",
  "requested_by": "550e8400-e29b-41d4-a716-446655440003",
  "requested_at": "2026-01-24T10:30:00Z",
  "expires_at": "2026-01-31T10:30:00Z",
  "is_expired": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Operation UUID"
    },
    "entity_id": {
      "type": "string",
      "description": "Entity UUID"
    },
    "operation_type": {
      "type": "number",
      "description": "Operation type code"
    },
    "operation_type_name": {
      "type": "string",
      "description": "Operation type name"
    },
    "target_table: `dictra_auth.users`": {
      "type": "string",
      "description": "Target table"
    },
    "target_id": {
      "type": "string",
      "description": "Target record UUID"
    },
    "status": {
      "type": "string",
      "enum": [
        "PENDING_LSO",
        "PENDING_RSO",
        "APPROVED",
        "REJECTED",
        "EXPIRED"
      ],
      "description": "Operation status"
    },
    "requested_by": {
      "type": "string",
      "description": "Requestor UUID"
    },
    "requested_at": {
      "type": "string",
      "description": "Request timestamp"
    },
    "expires_at": {
      "type": "string",
      "description": "Expiration timestamp"
    },
    "is_expired": {
      "type": "boolean",
      "description": "Whether operation has expired"
    }
  },
  "required": [
    "id",
    "entity_id",
    "operation_type",
    "operation_type_name",
    "target_table: `dictra_auth.users`",
    "status",
    "requested_by",
    "requested_at",
    "expires_at",
    "is_expired"
  ]
}

Get Pending Operation
GET`/api/v1/approvals/{id}`

Get pending operation details.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000

Approve LSO ¶

POST https://api.dictra.com.br/api/v1/approvals/550e8400-e29b-41d4-a716-446655440000/lso

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "comment": "Approved after review"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "comment": {
      "type": "string"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "message": "LSO approval successful",
  "status": "PENDING_RSO",
  "operation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entity_id": "550e8400-e29b-41d4-a716-446655440001",
    "operation_type": 1,
    "operation_type_name": "USER_REGISTRATION",
    "target_table: `dictra_auth.users`": "Hello, world!",
    "target_id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "PENDING_LSO",
    "requested_by": "550e8400-e29b-41d4-a716-446655440003",
    "requested_at": "2026-01-24T10:30:00Z",
    "expires_at": "2026-01-31T10:30:00Z",
    "is_expired": false
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "operation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Operation UUID"
        },
        "entity_id": {
          "type": "string",
          "description": "Entity UUID"
        },
        "operation_type": {
          "type": "number",
          "description": "Operation type code"
        },
        "operation_type_name": {
          "type": "string",
          "description": "Operation type name"
        },
        "target_table: `dictra_auth.users`": {
          "type": "string",
          "description": "Target table"
        },
        "target_id": {
          "type": "string",
          "description": "Target record UUID"
        },
        "status": {
          "type": "string",
          "enum": [
            "PENDING_LSO",
            "PENDING_RSO",
            "APPROVED",
            "REJECTED",
            "EXPIRED"
          ],
          "description": "Operation status"
        },
        "requested_by": {
          "type": "string",
          "description": "Requestor UUID"
        },
        "requested_at": {
          "type": "string",
          "description": "Request timestamp"
        },
        "expires_at": {
          "type": "string",
          "description": "Expiration timestamp"
        },
        "is_expired": {
          "type": "boolean",
          "description": "Whether operation has expired"
        }
      },
      "required": [
        "id",
        "entity_id",
        "operation_type",
        "operation_type_name",
        "target_table: `dictra_auth.users`",
        "status",
        "requested_by",
        "requested_at",
        "expires_at",
        "is_expired"
      ]
    }
  },
  "required": [
    "message",
    "status",
    "operation"
  ]
}

Approve LSO
POST`/api/v1/approvals/{id}/lso`

Perform first signature (LSO) approval.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000

Approve RSO ¶

POST https://api.dictra.com.br/api/v1/approvals/550e8400-e29b-41d4-a716-446655440000/rso

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "comment": "Final approval granted"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "comment": {
      "type": "string"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "message": "RSO approval successful - operation executed",
  "status": "APPROVED",
  "operation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entity_id": "550e8400-e29b-41d4-a716-446655440001",
    "operation_type": 1,
    "operation_type_name": "USER_REGISTRATION",
    "target_table: `dictra_auth.users`": "Hello, world!",
    "target_id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "PENDING_LSO",
    "requested_by": "550e8400-e29b-41d4-a716-446655440003",
    "requested_at": "2026-01-24T10:30:00Z",
    "expires_at": "2026-01-31T10:30:00Z",
    "is_expired": false
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "operation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Operation UUID"
        },
        "entity_id": {
          "type": "string",
          "description": "Entity UUID"
        },
        "operation_type": {
          "type": "number",
          "description": "Operation type code"
        },
        "operation_type_name": {
          "type": "string",
          "description": "Operation type name"
        },
        "target_table: `dictra_auth.users`": {
          "type": "string",
          "description": "Target table"
        },
        "target_id": {
          "type": "string",
          "description": "Target record UUID"
        },
        "status": {
          "type": "string",
          "enum": [
            "PENDING_LSO",
            "PENDING_RSO",
            "APPROVED",
            "REJECTED",
            "EXPIRED"
          ],
          "description": "Operation status"
        },
        "requested_by": {
          "type": "string",
          "description": "Requestor UUID"
        },
        "requested_at": {
          "type": "string",
          "description": "Request timestamp"
        },
        "expires_at": {
          "type": "string",
          "description": "Expiration timestamp"
        },
        "is_expired": {
          "type": "boolean",
          "description": "Whether operation has expired"
        }
      },
      "required": [
        "id",
        "entity_id",
        "operation_type",
        "operation_type_name",
        "target_table: `dictra_auth.users`",
        "status",
        "requested_by",
        "requested_at",
        "expires_at",
        "is_expired"
      ]
    }
  },
  "required": [
    "message",
    "status",
    "operation"
  ]
}

Approve RSO
POST`/api/v1/approvals/{id}/rso`

Perform second signature (RSO) approval. This executes the operation.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000

Reject Operation ¶

POST https://api.dictra.com.br/api/v1/approvals/550e8400-e29b-41d4-a716-446655440000/reject

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "reason": "Does not comply with security policy"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "reason": {
      "type": "string",
      "description": "Rejection reason (min 10 chars)"
    }
  },
  "required": [
    "reason"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "message": "Operation rejected",
  "status": "REJECTED",
  "operation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entity_id": "550e8400-e29b-41d4-a716-446655440001",
    "operation_type": 1,
    "operation_type_name": "USER_REGISTRATION",
    "target_table: `dictra_auth.users`": "Hello, world!",
    "target_id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "PENDING_LSO",
    "requested_by": "550e8400-e29b-41d4-a716-446655440003",
    "requested_at": "2026-01-24T10:30:00Z",
    "expires_at": "2026-01-31T10:30:00Z",
    "is_expired": false
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "operation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Operation UUID"
        },
        "entity_id": {
          "type": "string",
          "description": "Entity UUID"
        },
        "operation_type": {
          "type": "number",
          "description": "Operation type code"
        },
        "operation_type_name": {
          "type": "string",
          "description": "Operation type name"
        },
        "target_table: `dictra_auth.users`": {
          "type": "string",
          "description": "Target table"
        },
        "target_id": {
          "type": "string",
          "description": "Target record UUID"
        },
        "status": {
          "type": "string",
          "enum": [
            "PENDING_LSO",
            "PENDING_RSO",
            "APPROVED",
            "REJECTED",
            "EXPIRED"
          ],
          "description": "Operation status"
        },
        "requested_by": {
          "type": "string",
          "description": "Requestor UUID"
        },
        "requested_at": {
          "type": "string",
          "description": "Request timestamp"
        },
        "expires_at": {
          "type": "string",
          "description": "Expiration timestamp"
        },
        "is_expired": {
          "type": "boolean",
          "description": "Whether operation has expired"
        }
      },
      "required": [
        "id",
        "entity_id",
        "operation_type",
        "operation_type_name",
        "target_table: `dictra_auth.users`",
        "status",
        "requested_by",
        "requested_at",
        "expires_at",
        "is_expired"
      ]
    }
  },
  "required": [
    "message",
    "status",
    "operation"
  ]
}

Reject Operation
POST`/api/v1/approvals/{id}/reject`

Reject a pending operation.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000

Generated by aglio on 24 Jan 2026

API Endpoint

Features ¶

Authentication ¶

Error Codes ¶

Health & Status ¶

Health Check ¶

Headers

Body

Schema

Health CheckGET/health

Readiness Check ¶

Headers

Body

Schema

Headers

Body

Schema

Readiness CheckGET/ready

Authentication ¶

Login ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

LoginPOST/api/v1/auth/login

Refresh Token ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Refresh TokenPOST/api/v1/auth/refresh

Logout ¶

Headers

Headers

Body

Schema

LogoutPOST/api/v1/auth/logout

Get Current User ¶

Headers

Headers

Body

Schema

Get Current UserGET/api/v1/auth/me

Change Password ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Change PasswordPOST/api/v1/auth/change-password

Users ¶

List Users ¶

Headers

Headers

Body

Schema

List UsersGET/api/v1/users{?page,page_size,search,status,group_id,entity_id}

Get User ¶

Headers

Headers

Body

Schema

Headers

Features

Authentication

Error Codes

Health Check
GET`/health`

Readiness Check
GET`/ready`

Login
POST`/api/v1/auth/login`

Refresh Token
POST`/api/v1/auth/refresh`

Logout
POST`/api/v1/auth/logout`

Get Current User
GET`/api/v1/auth/me`

Change Password
POST`/api/v1/auth/change-password`

List Users
GET`/api/v1/users{?page,page_size,search,status,group_id,entity_id}`

Get User
GET`/api/v1/users/{id}`

Create User
POST`/api/v1/users`

Update User
PUT`/api/v1/users/{id}`

Deactivate User
DELETE`/api/v1/users/{id}`

List Entities
GET`/api/v1/entities{?page,page_size,search,status,type,consolidation_id}`

Get Entity
GET`/api/v1/entities/{id}`

Create Entity
POST`/api/v1/entities`

List Pending Operations
GET`/api/v1/approvals{?page,page_size,status,operation_type,requested_by,target_id,include_expired}`

Get Pending Operation
GET`/api/v1/approvals/{id}`