> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# List regions (legacy IAM)
> Legacy compatibility endpoint. New clients should use catalog.basaltic.sh/v1/regions.
This endpoint retains IAM-namespaced region CRNs and its existing response shape.
List all published regions. This endpoint is public and does not require authentication.
Returns all regions with their availability status.
Because it takes no credentials, requests are rate-limited per client IP.
Requires **no IAM action**. Access is decided by the endpoint's own
rules rather than by a policy — see the description above.
## OpenAPI
````yaml /api-reference/specs/iam.yaml get /v1/regions
openapi: 3.0.3
info:
title: Basaltic IAM API
version: 1.0.0
description: >
Account identity and access management: service accounts, roles, account
policies, and account-scoped temporary sessions. Authentication and personal
sign-in remain in IAM. Organizations, accounts, users, groups, and
organization policies are managed by the Workspace API.
Roles and custom policies belong to the selected account. Their global CRNs
use an empty region and the owning account handle. Shared system policies
use crn:iam:::policy/. Relationship inputs are classified once as CRN,
UUID, or name, without syntax fallback.
AssumeRole resolves the target role's owning account. The caller needs
source permission and the target role must trust the caller; the resulting
session uses only the target role's permissions, subject to boundaries and
session restrictions.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://iam.basaltic.sh
description: Global API endpoint
security:
- BearerAuth: []
paths:
/v1/regions:
get:
tags:
- Regions
summary: List regions (legacy IAM)
description: >
Legacy compatibility endpoint. New clients should use
catalog.basaltic.sh/v1/regions.
This endpoint retains IAM-namespaced region CRNs and its existing
response shape.
List all published regions. This endpoint is public and does not require
authentication.
Returns all regions with their availability status.
Because it takes no credentials, requests are rate-limited per client
IP.
operationId: listRegions
parameters:
- $ref: '#/components/parameters/IAMNameFilter'
- $ref: '#/components/parameters/IAMCRNFilter'
responses:
'200':
description: List of regions
content:
application/json:
schema:
type: object
required:
- regions
- default
properties:
regions:
type: array
description: List of available regions
items:
$ref: '#/components/schemas/Region'
default:
type: string
description: The default region code
example: sa-saopaulo-1
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
deprecated: true
security: []
components:
parameters:
IAMNameFilter:
name: name
in: query
allowEmptyValue: true
description: >-
Exact resource name, combined with crn using AND before pagination.
Empty values are filters. Resources without a name never match.
schema:
type: string
IAMCRNFilter:
name: crn
in: query
allowEmptyValue: true
description: >-
Exact returned CRN, combined with name using AND before pagination.
Malformed or empty CRNs return 400; valid mismatched or foreign CRNs
return an empty page. Resources without a CRN never match.
Organization-scoped CRNs use the authenticated organization.
schema:
type: string
schemas:
Region:
type: object
required:
- crn
- code
- name
- location
- country_code
- available
- coming_soon
properties:
crn:
type: string
description: >-
Platform-owned global region identity, using the immutable region
code.
example: crn:iam::platform:region/sa-saopaulo-1
code:
type: string
description: Unique region code used in API calls and CRNs
example: sa-saopaulo-1
name:
type: string
description: Human-readable region name
example: São Paulo 1
location:
type: string
description: Geographic location of the region
example: São Paulo, Brazil
country_code:
type: string
description: ISO 3166-1 alpha-2 country code (used to display flag in UI)
example: BR
minLength: 2
maxLength: 2
available:
type: boolean
description: Whether the region is currently available for use
example: true
coming_soon:
type: boolean
description: Whether the region is announced but not yet available
example: false
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Error code identifying the type of error
example: INVALID_INPUT
message:
type: string
description: Human-readable error message
example: Invalid request parameters
request_id:
type: string
format: uuid
description: Request ID for debugging
example: 550e8400-e29b-41d4-a716-446655440000
responses:
TooManyRequests:
description: >
Rate limit exceeded. The budget is a fixed window counted per endpoint
and
per caller — the authenticated principal when the request carries
credentials, the client IP otherwise — so one throttled endpoint never
spends another's budget, and one tenant never spends another's.
Wait `Retry-After` seconds, then retry. The `X-RateLimit-*` headers ride
on
the successful responses of a rate-limited endpoint too, so a client can
pace itself instead of discovering the ceiling by hitting it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: Too many requests, please try again later
request_id: 550e8400-e29b-41d4-a716-446655440000
headers:
Retry-After:
description: Seconds to wait before retrying. Never zero.
required: true
schema:
type: integer
minimum: 1
example: 42
X-RateLimit-Limit:
description: Requests allowed per window on this endpoint.
required: true
schema:
type: integer
minimum: 1
example: 5
X-RateLimit-Remaining:
description: Requests left in the current window. Always 0 on a 429.
required: true
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: >-
Seconds until the window resets — a duration, not a timestamp, so it
needs no clock agreement between client and server.
required: true
schema:
type: integer
minimum: 1
example: 42
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INTERNAL_ERROR
message: An internal error occurred
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
An OAuth 2.0 bearer token, sent as `Authorization: Bearer `.
This is the recommended way to authenticate.
Get one by exchanging a service account's access key pair at
`POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
standard client-credentials grant, so any OAuth-aware library will
obtain and refresh it for you.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Tokens last an hour by default. The same access key pair is separately
your AWS SigV4 credential for the S3-compatible object endpoint, which
speaks nothing else.
````