> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamosql.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Validate Role
> Verify that the schema's IAM role can be assumed and has DynamoDB access.
Required scope: `schemas:write`
## OpenAPI
````yaml POST /v1/schemas/{schemaName}/validate-role
openapi: 3.0.3
info:
title: DynamoSQL API
version: 0.1.0
license:
name: Proprietary
url: https://dynamosql.com
description: >
Complete API for DynamoSQL — authentication, SQL query planning and
execution, schema management, and usage metering.
All endpoints are reachable at `api.dynamosql.com`.
**Authentication** uses `POST /v1/auth/token` with your API client
credentials. See the [Authentication
guide](https://docs.dynamosql.com/guides/authentication)
for the full token exchange flow.
**API client scopes** control which endpoints a programmatic client can
access.
Valid scopes: `query`, `schemas:read`, `schemas:write`, `usage:read`.
Endpoints note their required scope in their description.
**Error responses** always follow the same envelope:
```json
{ "success": false, "error": { "message": "..." } }
```
servers:
- url: https://api.dynamosql.com
description: Production
security:
- cognitoJwt: []
tags:
- name: Authentication
description: >
Obtain a JWT bearer token using your API client credentials. This token is
required for all other endpoints. See the Authentication guide for details
on the token exchange flow and scope management.
- name: Query
description: SQL planning and execution.
- name: Schemas
description: >
Connect DynamoSQL to DynamoDB tables in your AWS account. A schema pairs a
name with the IAM role and AWS region DynamoSQL uses to assume
cross-account access.
- name: Usage
description: Metered usage — requests, rows returned, and DynamoDB read units.
paths:
/v1/schemas/{schemaName}/validate-role:
post:
tags:
- Schemas
summary: Validate schema IAM role
description: >
Validates that the schema's IAM role can be assumed and that DynamoSQL
has the expected access to the configured DynamoDB tables.
Validation steps: 1. Calls `sts:AssumeRole` with the schema's `roleArn`
and `externalId`. 2. If `tableAllowlist` contains `"*"`, lists all
DynamoDB tables
visible in the region to confirm broad read access.
3. If `tableAllowlist` contains explicit table names, calls
`DescribeTable` and a minimal `Scan` (limit 1) on each.
4. If no `tableAllowlist` is set, confirms only that the role
assumption succeeded.
The HTTP response is always `200 OK` regardless of whether validation
passed. Check `data.ok` and `data.message` for the actual result. This
allows callers to distinguish validation failures (wrong permissions)
from request errors (bad schema name).
Use this endpoint after creating a schema or after changing the role
ARN, external ID, or table allowlist to confirm the configuration is
correct before running queries.
API clients require the `schemas:write` scope.
operationId: validateSchemaRole
parameters:
- in: path
name: schemaName
required: true
schema:
type: string
description: The schema name to validate.
example: myschema
responses:
'200':
description: >
Validation complete. Check `data.ok` — `true` means the role and
table access are correctly configured. `false` means validation
failed; `data.message` contains details.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
required:
- ok
- message
properties:
ok:
type: boolean
description: >
`true` if role assumption and all table access
checks passed. `false` if any check failed.
message:
type: string
description: >
Human-readable outcome. On failure, includes the
specific error(s) encountered (up to 4 table-level
failures are listed).
examples:
success-explicit:
summary: Role valid — explicit allowlist
value:
success: true
data:
ok: true
message: >-
Assume role succeeded. Verified describe/read access for
3 allowlisted table(s) in us-east-1.
success-wildcard:
summary: Role valid — wildcard allowlist
value:
success: true
data:
ok: true
message: >-
Assume role succeeded. Wildcard allowlist enabled;
visible tables in us-east-1: 12.
success-no-allowlist:
summary: Role valid — no allowlist
value:
success: true
data:
ok: true
message: >-
Assume role succeeded. No explicit allowlisted tables to
validate.
failure-assume-role:
summary: Role assumption failed
value:
success: true
data:
ok: false
message: >-
User: arn:aws:iam::111222333444:role/DynamoSQL is not
authorized to assume role:
arn:aws:iam::123456789012:role/DynamoSQLReadRole
failure-table-access:
summary: Role assumed but table access denied
value:
success: true
data:
ok: false
message: >-
Assume role succeeded, but table access validation
failed for 1 check(s): Invoices (describe:
AccessDeniedException).
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
ApiResponse:
type: object
required:
- success
properties:
success:
type: boolean
description: >
`true` when the request was processed without errors, `false`
otherwise. Always present.
data: {}
error:
$ref: '#/components/schemas/ApiError'
ApiError:
type: object
description: Present in the response body when `success` is `false`.
properties:
message:
type: string
description: Human-readable description of what went wrong.
code:
type: string
description: Machine-readable error code, when available.
requestId:
type: string
description: |
Request correlation ID. Include this when contacting support.
responses:
BadRequest:
description: >
Validation error — a required field is missing, a value is out of range,
a date is malformed, or the request body is otherwise invalid. Check the
`error.message` field for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
success: false
error:
message: startDate must be before or equal to endDate
Unauthorized:
description: >
Missing `Authorization` header, expired JWT, or token issuer/audience
does not match the DynamoSQL Cognito user pool.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
success: false
error:
message: Unauthorized
Forbidden:
description: >
The caller lacks the required role or a tenant-scoping violation was
detected.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
success: false
error:
message: Tenant admin access required
securitySchemes:
cognitoJwt:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Bearer token obtained from `POST /v1/auth/token`. Pass in the
`Authorization` header as `Bearer `.
````