Service Accounts

Service accounts are non-human actors for programmatic API access. They authenticate using HMAC signatures with API keys.

The Service Account Object

{
  "id": "sa-bot001",
  "name": "CI/CD Bot",
  "description": "Automated deployment",
  "account_id": "acc-prod001",
  "organization_id": "org-abc123xyz",
  "is_active": true,
  "metadata": {},
  "created_at": "2025-09-30T10:00:00Z",
  "updated_at": "2025-09-30T10:00:00Z",
  "last_used_at": "2025-09-30T11:30:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the service account
`name`	string	Human-friendly name
`description`	string	Optional description
`account_id`	string	Account the service account belongs to
`organization_id`	string	Parent organization ID
`is_active`	boolean	Whether the service account is active
`metadata`	object	Optional metadata (key-value pairs)
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update
`last_used_at`	string	ISO 8601 timestamp of last API call (null if never used)

List Service Accounts

Retrieves a paginated list of service accounts.

GET /service-accounts

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`quantity`	integer	20	Results per page (max: 100)
`order_by`	string	`-created_at`	Sort field
`account_id`	string	-	Filter by account

Example Request

curl "https://api.console.solucao42.com.br/service-accounts?page=1" \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Example Response

{
  "total": 5,
  "page": 1,
  "results": [
    {
      "id": "sa-bot001",
      "name": "CI/CD Bot",
      "description": "Automated deployment",
      "account_id": "acc-prod001",
      "organization_id": "org-abc123xyz",
      "is_active": true,
      "metadata": {},
      "created_at": "2025-09-30T10:00:00Z",
      "updated_at": "2025-09-30T10:00:00Z",
      "last_used_at": "2025-09-30T11:30:00Z"
    }
  ]
}

Get Service Account

Retrieves a specific service account by ID.

GET /service-accounts/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Service account ID

Example Request

curl https://api.console.solucao42.com.br/service-accounts/sa-bot001 \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Example Response

{
  "id": "sa-bot001",
  "name": "CI/CD Bot",
  "description": "Automated deployment",
  "account_id": "acc-prod001",
  "organization_id": "org-abc123xyz",
  "is_active": true,
  "metadata": {
    "purpose": "ci_cd",
    "environment": "production"
  },
  "created_at": "2025-09-30T10:00:00Z",
  "updated_at": "2025-09-30T10:00:00Z",
  "last_used_at": "2025-09-30T11:30:00Z"
}

Create Service Account

Creates a new service account.

POST /service-accounts

Request Body

{
  "name": "CI/CD Bot",
  "description": "Automated deployment",
  "account_id": "acc-prod001",
  "metadata": {
    "purpose": "ci_cd",
    "environment": "production"
  }
}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Service account name
`description`	string	No	Description
`account_id`	string	Yes	Account ID
`metadata`	object	No	Optional metadata

Example Request

curl -X POST https://api.console.solucao42.com.br/service-accounts \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "Content-Type: application/json" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: <body-hash>" \
  -d '{
    "name": "CI/CD Bot",
    "description": "Automated deployment",
    "account_id": "acc-prod001"
  }'

Example Response

{
  "id": "sa-bot002",
  "name": "CI/CD Bot",
  "description": "Automated deployment",
  "account_id": "acc-prod001",
  "organization_id": "org-abc123xyz",
  "is_active": true,
  "metadata": {},
  "created_at": "2025-09-30T12:00:00Z",
  "updated_at": "2025-09-30T12:00:00Z",
  "last_used_at": null
}

Update Service Account

Updates an existing service account.

PATCH /service-accounts/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Service account ID

Request Body

{
  "name": "CI/CD Production Bot",
  "description": "Production deployments only",
  "is_active": true
}

Example Request

curl -X PATCH https://api.console.solucao42.com.br/service-accounts/sa-bot001 \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "Content-Type: application/json" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: <body-hash>" \
  -d '{
    "description": "Production deployments only"
  }'

Example Response

{
  "id": "sa-bot001",
  "name": "CI/CD Bot",
  "description": "Production deployments only",
  "account_id": "acc-prod001",
  "organization_id": "org-abc123xyz",
  "is_active": true,
  "metadata": {},
  "created_at": "2025-09-30T10:00:00Z",
  "updated_at": "2025-09-30T12:30:00Z",
  "last_used_at": "2025-09-30T11:30:00Z"
}

Delete Service Account

Deletes a service account. All associated API keys are revoked.

DELETE /service-accounts/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Service account ID

Example Request

curl -X DELETE https://api.console.solucao42.com.br/service-accounts/sa-old001 \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Response

204 No Content

API Key Operations

Issue API Key

Creates a new API key for the service account.

POST /service-accounts/{id}/keys

Request Body

{
  "description": "Production key",
  "expires_at": "2026-12-31T23:59:59Z"
}

Example Request

curl -X POST https://api.console.solucao42.com.br/service-accounts/sa-bot001/keys \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "Content-Type: application/json" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: <body-hash>" \
  -d '{
    "description": "Production key",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Example Response

{
  "id": "key-xyz789",
  "access_key": "sa_abc123_acc456_xyz789",
  "secret_key": "AbCdEf123456789...",
  "description": "Production key",
  "service_account_id": "sa-bot001",
  "expires_at": "2026-12-31T23:59:59Z",
  "is_active": true,
  "created_at": "2025-09-30T12:00:00Z",
  "last_used_at": null
}

:class: warning
The `secret_key` is only shown once! Store it securely immediately.

List API Keys

Lists all API keys for a service account.

GET /service-accounts/{id}/keys

Example Request

curl https://api.console.solucao42.com.br/service-accounts/sa-bot001/keys \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Example Response

{
  "total": 2,
  "page": 1,
  "results": [
    {
      "id": "key-xyz789",
      "access_key": "sa_abc123_acc456_xyz789",
      "description": "Production key",
      "service_account_id": "sa-bot001",
      "expires_at": "2026-12-31T23:59:59Z",
      "is_active": true,
      "created_at": "2025-09-30T12:00:00Z",
      "last_used_at": "2025-09-30T12:30:00Z"
    }
  ]
}

Note: secret_key is never returned after initial creation.

Revoke API Key

Revokes an API key immediately.

DELETE /service-accounts/{id}/keys/{key_id}

Example Request

curl -X DELETE https://api.console.solucao42.com.br/service-accounts/sa-bot001/keys/key-xyz789 \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "x-date: 2025-09-30T12:00:00Z" \
  -H "x-nonce: unique-request-id" \
  -H "x-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Response

204 No Content

Response Codes

Code	Description
200	Success
201	Created
204	No Content (delete successful)
400	Invalid request body
401	Authentication failed
403	Insufficient permissions
404	Service account not found
422	Validation error

Permissions

Required Permissions

Action	Permission
List service accounts	`service-accounts:ListServiceAccounts`
Get service account	`service-accounts:GetServiceAccount`
Create service account	`service-accounts:CreateServiceAccount`
Update service account	`service-accounts:UpdateServiceAccount`
Delete service account	`service-accounts:DeleteServiceAccount`
Issue API key	`service-accounts:IssueKey`
List API keys	`service-accounts:ListKeys`
Revoke API key	`service-accounts:RevokeKey`

Accounts - Service accounts belong to accounts
Groups - Service account group memberships
Policies - Service account permissions

Notes

Service accounts belong to exactly one account
API keys use HMAC-SHA256 signatures for authentication
The access_key format is sa_{org_slug}_{account_id}_{random}
Secret keys are hashed and cannot be retrieved after creation
Revoking an API key takes effect immediately
Service accounts have the same permission model as users

The Service Account Object​

Attributes​

List Service Accounts​

Query Parameters​

Example Request​

Example Response​

Get Service Account​

Path Parameters​

Example Request​

Example Response​

Create Service Account​

Request Body​

Parameters​

Example Request​

Example Response​

Update Service Account​

Path Parameters​

Request Body​

Example Request​

Example Response​

Delete Service Account​

Path Parameters​

Example Request​

Response​

API Key Operations​

Issue API Key​

Request Body​

Example Request​

Example Response​

List API Keys​

Example Request​

Example Response​

Revoke API Key​

Example Request​

Response​

Response Codes​

Permissions​

Required Permissions​

Related Resources​

Notes​

The Service Account Object

Attributes

List Service Accounts

Query Parameters

Example Request

Example Response

Get Service Account

Path Parameters

Example Request

Example Response

Create Service Account

Request Body

Parameters

Example Request

Example Response

Update Service Account

Path Parameters

Request Body

Example Request

Example Response

Delete Service Account

Path Parameters

Example Request

Response

API Key Operations

Issue API Key

Request Body

Example Request

Example Response

List API Keys

Example Request

Example Response

Revoke API Key

Example Request

Response

Response Codes

Permissions

Required Permissions

Related Resources

Notes