> ## 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. # Assume role > Assume an IAM role and receive temporary credentials. The caller must be allowed by the role's trust policy. Can be used by service accounts to get temporary credentials for a specific role. An optional `policy` scopes the session down to less than the role grants; see `SessionPolicyDocument`. ## OpenAPI ````yaml /api-reference/specs/iam.yaml post /v1/assume-role openapi: 3.0.3 info: title: Basaltic IAM API version: 1.0.0 description: | Identity for the platform: organizations, accounts, users, groups, service accounts, roles and policies, together with the sign-in flows and the temporary STS credentials every other Basaltic API authenticates against. 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: - SignatureAuth: [] paths: /v1/assume-role: post: tags: - IAM summary: Assume role description: > Assume an IAM role and receive temporary credentials. The caller must be allowed by the role's trust policy. Can be used by service accounts to get temporary credentials for a specific role. An optional `policy` scopes the session down to less than the role grants; see `SessionPolicyDocument`. operationId: assumeRole requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssumeRoleRequest' responses: '200': description: Role assumed successfully content: application/json: schema: $ref: '#/components/schemas/AssumeRoleResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: Not allowed to assume this role content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - SignatureAuth: [] components: schemas: AssumeRoleRequest: type: object required: - role_id properties: role_id: type: string format: uuid example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 duration_seconds: type: integer minimum: 900 maximum: 43200 default: 3600 description: Credential validity duration (15 min to 12 hours) example: 3600 policy: $ref: '#/components/schemas/SessionPolicyDocument' AssumeRoleResponse: type: object properties: access_key_id: type: string example: AKIA... secret_access_key: type: string example: wJalrXUtnFEMI... session_token: type: string example: FwoGZXIvYXdzE... expiration: type: string format: date-time example: '2026-01-15T09:30:00Z' 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 SessionPolicyDocument: type: object description: > An inline policy that scopes down the credentials being minted. It grants nothing on its own: every request made with the resulting credentials must be allowed by the caller's identity policies *and* by this document, so it can only narrow what the caller already has. The document is validated on the way in and stored with the session — an invalid one fails the call with `INVALID_INPUT` rather than being ignored. Statements take the same shape as in a managed policy but carry no `conditions`; a session policy fences on actions and resources only. required: - version - statements properties: version: type: string enum: - '2024-01-01' example: '2024-01-01' statements: type: array minItems: 1 items: $ref: '#/components/schemas/SessionPolicyStatement' example: version: '2024-01-01' statements: - effect: allow actions: - storage:GetObject resources: - crn:storage:sa-saopaulo-1::bucket/reports/* SessionPolicyStatement: type: object description: | A session-policy statement. Same action/resource exclusivity as `PolicyStatement` — exactly one of `actions`/`not_actions` and one of `resources`/`not_resources`. required: - effect allOf: - oneOf: - required: - actions - required: - not_actions - oneOf: - required: - resources - required: - not_resources properties: sid: type: string description: Statement identifier example: OnlyReports effect: type: string enum: - allow - deny example: allow actions: type: array minItems: 1 items: type: string description: Actions in service:action format example: - storage:GetObject not_actions: type: array minItems: 1 items: type: string description: The statement covers every action except these example: - iam:* resources: type: array minItems: 1 items: type: string description: Resource identifiers or patterns example: - crn:storage:sa-saopaulo-1::bucket/reports/* not_resources: type: array minItems: 1 items: type: string description: The statement covers every resource except these example: - crn:iam:::user/* responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 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: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````