---
title: IAM Permissions - Amazon Bedrock API Gateway Access Policies
description: Complete AWS IAM permission reference for stdapi.ai, including required
  Amazon Bedrock policies, feature-specific statements, and full policy examples.
keywords: IAM permissions Bedrock, AWS IAM policy, Bedrock IAM actions, least privilege
  AWS, S3 IAM policy, Polly IAM, Transcribe IAM, API gateway permissions
---

# :material-shield-key: IAM Permissions

Every AWS call stdapi.ai makes is signed with the credentials of the role it runs under. This page lists, feature by feature, the exact IAM statements that role needs, and ends with complete policy examples.

**Who this page is for.** If you deploy with the official [Terraform module](https://github.com/stdapi-ai/terraform-aws-stdapi-ai), it already provisions the ECS task role with every statement below — you need this page only to audit what that role can do, or to restrict it further. Read it in full when you build the role yourself: a manual ECS or EC2 deployment, a container running outside AWS, or an IAM user for local development.

!!! info "Building your policy"
    Combine the statements below based on the features you enable. At minimum, you need the **Bedrock** permissions; add S3, TTS, STT and the others only as your deployment requires them (least privilege).

    A customer managed policy is capped at **6,144 characters**, a limit AWS does not raise through Service Quotas, and whitespace does not count toward it. Enabling most of the features on this page exceeds that in a single document — `CreatePolicy` then fails with `LimitExceeded: Cannot exceed quota for PolicySize: 6144`, naming no statement. Attach several policies to the role instead of widening actions to save characters: splitting by service keeps each one readable and reviewable, the Terraform module ships two for exactly this reason (one for Amazon Bedrock, one for the supporting services), and a role takes up to 10 managed policies by default.

---

## :material-table: Which Sections Do You Need? { #feature-specific-permission-requirements }

Each row below is one section of this page. Find the features your deployment enables, then read the sections they point to.

| Feature | Required Permissions | Configuration |
|---------|----------------------|---------------|
| **[Bedrock](#bedrock-iam)** | `bedrock:CountTokens`<br>`bedrock:InvokeGuardrailChecks`<br>`bedrock:InvokeModel`<br>`bedrock:InvokeModelWithBidirectionalStream`<br>`bedrock:InvokeModelWithResponseStream`<br>`bedrock:InvokeTool` (the Amazon Nova grounding server tool)<br>`bedrock:Rerank`<br>`bedrock:GetAsyncInvoke` and `bedrock:TagResource` (on `arn:aws:bedrock:*:*:async-invoke/*`) for async-invoke models (video, TwelveLabs Marengo embeddings)<br>For model discovery: `bedrock:ListFoundationModels`<br>`bedrock:GetFoundationModelAvailability`<br>`bedrock:ListProvisionedModelThroughputs`<br>`bedrock:ListInferenceProfiles`<br>The Realtime API (`POST /v1/realtime/client_secrets`, `WS /v1/realtime`) needs no additional action: `bedrock:InvokeModelWithBidirectionalStream` covers it | Always required |
| **[Bedrock Marketplace Auto-Subscribe](#bedrock-marketplace-auto-subscribe-iam)** | `aws-marketplace:Subscribe`<br>`aws-marketplace:ViewSubscriptions` | `AWS_BEDROCK_MARKETPLACE_AUTO_SUBSCRIBE=true` (default) |
| **[Bedrock Marketplace Model Endpoints](#bedrock-marketplace-endpoints-iam)** | `bedrock:ListMarketplaceModelEndpoints`<br>`bedrock:GetMarketplaceModelEndpoint`<br>`sagemaker:InvokeEndpoint`<br>`sagemaker:InvokeEndpointWithResponseStream` (on `arn:aws:sagemaker:*:*:endpoint/*`, conditioned on `aws:CalledViaLast: bedrock.amazonaws.com`) | `AWS_BEDROCK_MARKETPLACE_ENDPOINTS_ENABLED=true` |
| **[SageMaker AI Endpoints](#sagemaker-endpoints-iam)** | `sagemaker:CallWithBearerToken` (on `*`, no resource-level support)<br>`sagemaker:InvokeEndpoint` (on the endpoint ARNs you serve) | `AWS_SAGEMAKER_ENDPOINTS` configured |
| **[Bedrock Inference Profiles, Prompt Routers and Prompt Management](#bedrock-inference-profiles-and-prompt-routers-optional)** | `bedrock:GetInferenceProfile`<br>`bedrock:GetPromptRouter`<br>`bedrock:GetPrompt` and `bedrock:RenderPrompt` (on `arn:aws:bedrock:*:*:prompt/*`) for Prompt Management prompts | `AWS_BEDROCK_ALLOW_*_ARN=true` or `AWS_BEDROCK_MODEL_ARN_MAPPING` configured |
| **[Bedrock Guardrails](#bedrock-guardrails-optional)** | `bedrock:ApplyGuardrail` | `AWS_BEDROCK_GUARDRAIL_IDENTIFIER` |
| **[Bedrock Session Storage](#bedrock-session-storage-optional)** | Bedrock session permissions (`bedrock:CreateSession`, `bedrock:GetSession`, `bedrock:*Invocation*`, `bedrock:ListSessions`, `bedrock:EndSession`, `bedrock:DeleteSession`, `bedrock:TagResource`, `bedrock:ListTagsForResource` on sessions) | `store=true` requests and stored-completion listings |
| **[Bedrock Mantle](#bedrock-mantle-iam)** | `bedrock-mantle:CreateInference`<br>`bedrock-mantle:GetInference`<br>`bedrock-mantle:DeleteInference`<br>`bedrock-mantle:ListModels`<br>`bedrock-mantle:GetModel`<br>`bedrock-mantle:CancelInference`<br>`bedrock-mantle:CountTokens` (on `arn:aws:bedrock-mantle:*:*:project/*`)<br>`bedrock-mantle:CallWithBearerToken` | `AWS_BEDROCK_MANTLE_ENABLED=true` |
| **[Web Search](#web-search-iam)** | `bedrock-websearch:InvokeSearch`<br>`bedrock-websearch:InvokeFetch`<br>`bedrock-websearch:ExternalWebAccess` only when external web access is enabled | `web_search` requests on the OpenAI GPT-5.x family |
| **[S3 File Storage](#s3-file-storage-optional)** | `s3:PutObject`<br>`s3:PutObjectTagging`<br>`s3:GetObject`<br>`s3:DeleteObject`<br>`s3:AbortMultipartUpload`<br>`s3:ListMultipartUploadParts`<br>`s3:ListBucket`<br>`s3:ListBucketMultipartUploads`<br>on every bucket, including each `AWS_S3_REGIONAL_BUCKETS` entry<br>`kms:Decrypt` and `kms:GenerateDataKey`, with a `kms:ViaService` condition, when the buckets use KMS encryption | `AWS_S3_BUCKET`<br>`AWS_S3_REGIONAL_BUCKETS`<br>If S3 buckets use KMS encryption |
| **[S3 Accepted Input Buckets](#s3-accepted-input-buckets)** | `s3:GetObject` on the objects of each declared bucket (no `s3:ListBucket`)<br>`kms:Decrypt`, with a `kms:ViaService` condition, when those buckets use KMS encryption | `AWS_S3_ACCEPTED_BUCKETS`<br>If those buckets use KMS encryption |
| **[Vector Stores](#vector-stores-optional)** | `s3vectors:CreateIndex`<br>`s3vectors:DeleteIndex`<br>`s3vectors:PutVectors`<br>`s3vectors:GetVectors`<br>`s3vectors:QueryVectors`<br>`s3vectors:DeleteVectors` (on the vector bucket and its indexes)<br>File Storage S3 permissions on `AWS_S3_BUCKET` for the stores' records<br>`kms:Decrypt` and `kms:GenerateDataKey`, with a `kms:ViaService` condition, when the vector bucket uses KMS encryption | `AWS_S3_VECTORS_BUCKET`<br>`AWS_S3_VECTORS_REGION` |
| **[Durable Vector Store Indexing](#durable-vector-store-indexing)** | `sqs:SendMessage`<br>`sqs:ReceiveMessage`<br>`sqs:DeleteMessage`<br>`sqs:ChangeMessageVisibility`<br>`sqs:GetQueueAttributes` (on the queue ARN only)<br>`kms:Decrypt` and `kms:GenerateDataKey`, with a `kms:ViaService` condition, when the queue uses SSE-KMS with your own key | `AWS_SQS_VECTOR_STORE_QUEUE_URL` |
| **[Shared Table](#shared-table)** | `dynamodb:GetItem`<br>`dynamodb:PutItem`<br>`dynamodb:DeleteItem`<br>`dynamodb:Query`<br>`dynamodb:DescribeTable`<br>`dynamodb:DescribeTimeToLive` (on the table ARN; no `dynamodb:Scan`, no index ARN)<br>`dynamodb:UpdateItem` on the `LIMIT#*` items only, when any tenant is rate limited<br>`kms:Decrypt` on the key, with a `kms:ViaService` condition, when the table uses your own key | `AWS_DYNAMODB_TABLE`<br>`AWS_DYNAMODB_REGION`<br>`MODEL_CACHE_SHARED`<br>`TENANT_RATE_LIMIT_REQUESTS_PER_MINUTE`<br>`TENANT_RATE_LIMIT_TOKENS_PER_MINUTE` |
| **[Tenant API Key Delivery](#tenant-key-delivery)** | `ssm:PutParameter`<br>`ssm:GetParameter` (on the delivery prefix)<br>`kms:Encrypt`, `kms:Decrypt`, `kms:GenerateDataKey` on the key, with a `kms:ViaService` condition, when `TENANT_KEY_SSM_KMS_KEY_ID` names a key of your own<br>plus the Shared Table permissions above | `TENANT_API_KEYS` (unless `TENANT_KEY_SECRETSMANAGER_PREFIX` is set)<br>`TENANT_KEY_SSM_PARAMETER_PREFIX`<br>`TENANT_KEY_SSM_KMS_KEY_ID` |
| **[Tenant API Key Rotation](#tenant-key-rotation)** | `secretsmanager:CreateSecret`<br>`secretsmanager:DescribeSecret`<br>`secretsmanager:GetSecretValue`<br>`secretsmanager:PutSecretValue`<br>`secretsmanager:UpdateSecretVersionStage` (on the secret prefix; replaces the Parameter Store delivery)<br>`kms:GenerateDataKey`, `kms:Decrypt` on the key, with a `kms:ViaService` condition, when `TENANT_KEY_SECRETSMANAGER_KMS_KEY_ID` names a key of your own<br>plus the Shared Table permissions above | `TENANT_KEY_SECRETSMANAGER_PREFIX`<br>`TENANT_KEY_SECRETSMANAGER_KMS_KEY_ID`<br>`TENANT_KEY_ROTATION_DAYS` |
| **[Tenant AWS Credentials](#tenant-aws-credentials)** | `sts:AssumeRole` on the tenant role ARNs, conditioned on `sts:ExternalId` | `TENANT_AWS_CREDENTIALS` |
| **[Knowledge Base Vector Stores](#knowledge-base-vector-stores)** | `bedrock:GetKnowledgeBase`<br>`bedrock:Retrieve`<br>`bedrock:ListDataSources`<br>`bedrock:IngestKnowledgeBaseDocuments`<br>`bedrock:ListKnowledgeBaseDocuments`<br>`bedrock:GetKnowledgeBaseDocuments`<br>`bedrock:DeleteKnowledgeBaseDocuments` (on each allowlisted knowledge base ARN; no `bedrock:ListKnowledgeBases`) | `AWS_BEDROCK_KNOWLEDGE_BASE_IDS` |
| **[Video Generation](#video-generation-optional)** | Core Bedrock invoke permissions (incl. `bedrock:GetAsyncInvoke`, `bedrock:TagResource`)<br>`bedrock:ListAsyncInvokes` and `bedrock:ListTagsForResource` (on `arn:aws:bedrock:*:*:async-invoke/*`) for job listing<br>File Storage S3 permissions on each regional bucket | `AWS_S3_REGIONAL_BUCKETS` |
| **[Batch Inference](#batch-inference)** | `bedrock:CreateModelInvocationJob`<br>`bedrock:GetModelInvocationJob`<br>`bedrock:StopModelInvocationJob` (on `arn:aws:bedrock:*:*:model-invocation-job/*`)<br>`iam:PassRole` on the batch service role, scoped with `iam:PassedToService: bedrock.amazonaws.com`<br>File Storage S3 permissions on each bucket a batch uses, plus the service role's own policy | `AWS_BEDROCK_BATCH_ROLE_ARN` |
| **[Text-to-Speech](#text-to-speech-optional)** | `polly:SynthesizeSpeech`<br>`polly:DescribeVoices`<br>`polly:StartSpeechSynthesisStream` for generative voices above 3,000 characters<br>`polly:StartSpeechSynthesisTask`, `polly:GetSpeechSynthesisTask` and S3 `PutObject`/`GetObject`/`DeleteObject` on each bucket serving a Polly region, for the other voices above 3,000 characters | `AWS_POLLY_REGION`<br>`AWS_S3_BUCKET`<br>`AWS_S3_REGIONAL_BUCKETS` |
| **[Speech-to-Text](#speech-to-text-optional)** | `transcribe:StartTranscriptionJob`<br>`transcribe:GetTranscriptionJob`<br>`transcribe:DeleteTranscriptionJob`<br>`transcribe:StartStreamTranscription`<br>`transcribe:TagResource` (on `arn:aws:transcribe:*:*:transcription-job/*` and `medical-transcription-job/*`)<br>For medical transcription: `transcribe:StartMedicalTranscriptionJob`, `transcribe:StartMedicalStreamTranscription`, and `transcribe:GetMedicalTranscriptionJob`, `transcribe:DeleteMedicalTranscriptionJob` (on `arn:aws:transcribe:*:*:medical-transcription-job/*`)<br>File Storage S3 permissions on every bucket serving a candidate region<br>`kms:GenerateDataKey`, `kms:Decrypt` on the output encryption key, when one is configured | `AWS_TRANSCRIBE_REGION`<br>`AWS_TRANSCRIBE_S3_BUCKET`<br>`AWS_S3_REGIONAL_BUCKETS`<br>`AWS_TRANSCRIBE_STREAM_LANGUAGES`<br>`AWS_TRANSCRIBE_OUTPUT_ENCRYPTION_KEY_ARN` |
| **[Language Detection](#language-detection-optional)** | `comprehend:DetectDominantLanguage` | `AWS_COMPREHEND_REGION` |
| **[Comprehend Moderation](#comprehend-moderation)** | `comprehend:DetectToxicContent` | Moderations API without a configured guardrail |
| **[Text Translation](#text-translation-optional)** | `translate:TranslateText`<br>`translate:ListLanguages` (optional; validates the language pair before transcribing) | `AWS_TRANSLATE_REGION` |
| **[Cost Tracking](#cost-tracking-iam)** | `pricing:GetProducts` | `COST_TRACKING=true` (opt-in; `false` by default) |
| **[Usage API](#usage-api-iam)** | `cloudwatch:GetMetricData`<br>`cloudwatch:ListMetrics` (on `*` — [CloudWatch metric actions take no resource ARN](#usage-api-iam)); `GetMetricData` is billed per metric read and is outside the free tier | `USAGE_API=true` (opt-in; `false` by default), with `CLOUDWATCH_METRICS=true` |
| **[Per-User Cost Attribution](#per-user-cost-attribution)** | `sts:AssumeRole` and `sts:TagSession` on the end user role, matched by that role's trust policy; on the end user role itself, `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream` on every model ARN form the deployment allows, plus `bedrock:ApplyGuardrail` when a guardrail is configured and `s3:GetObject` (with `kms:Decrypt` via S3) on every bucket an invocation can reference by URI | `AWS_BEDROCK_USER_ROLE_ARN` |
| **[API Key Authentication](#api-key-authentication-optional)** | Parameter Store: `ssm:GetParameter`<br>`kms:Decrypt` (if encrypted)<br>Secrets Manager: `secretsmanager:GetSecretValue` | `API_KEY_SSM_PARAMETER`<br>`API_KEY_SECRETSMANAGER_SECRET` |

!!! warning "Multi-Region Failover and Region-Scoped Policies"
    By default, Amazon Bedrock **and** the other AWS AI services (Polly, Transcribe, Comprehend, Translate) are called in every region listed in [`AWS_BEDROCK_REGIONS`](operations_configuration_aws.md#aws-bedrock-regions), failing over from one to the next on throttling, quota, or availability errors. See [Other AWS Services Failover](operations_resilience.md#other-aws-services-failover).

    The statements on this page use region-agnostic resources, so they work as-is. However, any `aws:RequestedRegion` condition — in the policy itself, a permissions boundary, or a service control policy — must allow **all** configured regions, otherwise failover silently fails and requests error out once the first region is unavailable.

---

## :material-aws: Bedrock (Required) { #bedrock-iam }

**Environment Variables**: Always required

These permissions are mandatory for stdapi.ai to discover and invoke Amazon Bedrock models:

??? example "Bedrock IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockModelInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:CountTokens",
        "bedrock:GetAsyncInvoke",
        "bedrock:InvokeGuardrailChecks",
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithBidirectionalStream",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:InvokeTool",
        "bedrock:Rerank"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BedrockAsyncInvokeTagging",
      "Effect": "Allow",
      "Action": [
        "bedrock:TagResource"
      ],
      "Resource": "arn:aws:bedrock:*:*:async-invoke/*"
    },
    {
      "Sid": "BedrockModelDiscovery",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListFoundationModels",
        "bedrock:GetFoundationModelAvailability",
        "bedrock:ListProvisionedModelThroughputs",
        "bedrock:ListInferenceProfiles"
      ],
      "Resource": "*"
    }
    ```

!!! note "Asynchronous Invocations"
    `bedrock:GetAsyncInvoke` and `bedrock:TagResource` (on `arn:aws:bedrock:*:*:async-invoke/*`) serve Bedrock asynchronous invocations, used by video generation models and asynchronous embedding models such as TwelveLabs Marengo (`twelvelabs.marengo-embed-*`). They can be dropped if your deployment uses none of these models. `bedrock:ListAsyncInvokes` and `bedrock:ListTagsForResource` are **not** part of this core set — they are only needed for video job listing (see [Video Generation](#video-generation-optional)).

!!! note "Bidirectional Streaming"
    `bedrock:InvokeModelWithBidirectionalStream` serves any model invoked over a persistent, two-way connection: live audio transcription with Amazon Nova Sonic (see [Speech-to-Text](#speech-to-text-optional)) and the [Realtime API](api_openai_realtime.md) (`POST /v1/realtime/client_secrets`, `WS /v1/realtime`) alike. No route-specific action exists for either — it is already part of the core Bedrock policy above.

---

## :material-storefront: Bedrock Marketplace Auto-Subscribe (Optional) { #bedrock-marketplace-auto-subscribe-iam }

**Environment Variables**: [`AWS_BEDROCK_MARKETPLACE_AUTO_SUBSCRIBE`](operations_configuration_models.md#bedrock-marketplace-auto-subscribe)

Required only if you want models sold as third-party AWS Marketplace listings to be usable without subscribing to each one by hand (`AWS_BEDROCK_MARKETPLACE_AUTO_SUBSCRIBE=true`, which is the default). The server never calls `Subscribe` itself: it keeps a listing with no agreement in the catalogue, and AWS creates the subscription under this role on the first invocation. It applies to whichever models AWS sells that way — see [Which Models Are Which](operations_cost_management.md#which-models-are-which); models billed as ordinary Amazon Bedrock usage need none of these permissions.

??? example "Bedrock Marketplace Auto-Subscribe IAM Policy Statement"
    ```json
    {
      "Sid": "BedrockMarketplaceAutoSubscribe",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:Subscribe",
        "aws-marketplace:ViewSubscriptions"
      ],
      "Resource": "*"
    }
    ```

    !!! warning "Cost Consideration"
        Automatic marketplace subscriptions may incur costs. Review AWS Marketplace pricing for individual models before enabling this feature, or set `AWS_BEDROCK_MARKETPLACE_AUTO_SUBSCRIBE=false` to require manual marketplace subscription.

---

## :material-server-network: Bedrock Marketplace Model Endpoints (Optional) { #bedrock-marketplace-endpoints-iam }

**Environment Variables**: [`AWS_BEDROCK_MARKETPLACE_ENDPOINTS_ENABLED`](operations_configuration_models.md#bedrock-marketplace-endpoints-enabled)

Required only if you want stdapi.ai to publish and serve the Amazon Bedrock Marketplace model endpoints already deployed in this account. The server only discovers and invokes them — it never creates, updates or deletes an endpoint, so it is granted no action that does.

??? example "Bedrock Marketplace Model Endpoints IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockMarketplaceEndpointDiscovery",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListMarketplaceModelEndpoints",
        "bedrock:GetMarketplaceModelEndpoint"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BedrockMarketplaceEndpointInvoke",
      "Effect": "Allow",
      "Action": [
        "sagemaker:InvokeEndpoint",
        "sagemaker:InvokeEndpointWithResponseStream"
      ],
      "Resource": "arn:aws:sagemaker:*:<account-id>:endpoint/*",
      "Condition": {
        "StringEquals": {
          "aws:CalledViaLast": "bedrock.amazonaws.com"
        }
      }
    }
    ```

    Neither `ListMarketplaceModelEndpoints` nor `GetMarketplaceModelEndpoint` takes a resource-level scope, hence `Resource: "*"` on discovery. `sagemaker:InvokeEndpoint` is what Amazon Bedrock calls on the server's behalf when it forwards an invocation to the endpoint, which is why it is conditioned on `aws:CalledViaLast: bedrock.amazonaws.com` — under this policy, the role can never call a SageMaker endpoint directly, only through Bedrock.

    See [Set up model access for Amazon Bedrock Marketplace](https://docs.aws.amazon.com/bedrock/latest/userguide/setup-amazon-bedrock-marketplace.html).

---

## :material-server: SageMaker AI Endpoints (Optional) { #sagemaker-endpoints-iam }

**Environment Variables**: [`AWS_SAGEMAKER_ENDPOINTS`](operations_configuration_models.md#aws-sagemaker-endpoints)

Required only if you name Amazon SageMaker AI endpoints for stdapi.ai to serve. The server only invokes the endpoints you named — it never creates, updates, scales or deletes one, so it is granted no action that does.

??? example "SageMaker AI Endpoints IAM Policy Statements"
    ```json
    {
      "Sid": "SageMakerBearerToken",
      "Effect": "Allow",
      "Action": "sagemaker:CallWithBearerToken",
      "Resource": "*"
    },
    {
      "Sid": "SageMakerEndpointInvoke",
      "Effect": "Allow",
      "Action": "sagemaker:InvokeEndpoint",
      "Resource": [
        "arn:aws:sagemaker:<region>:<account-id>:endpoint/<endpoint-name>"
      ]
    }
    ```

    The OpenAI-compatible route authenticates with a short-term API key the server derives locally from its own credentials, which is what `sagemaker:CallWithBearerToken` authorizes; the action supports no resource-level scope, hence `Resource: "*"`. That key carries the same authority as the role, so **`sagemaker:InvokeEndpoint` is what bounds it** — list the endpoint ARNs you actually serve rather than `*`, and a leaked key can still reach nothing else.

    See [OpenAI-compatible endpoints](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-openai-compatible.html).

---

## :material-directions-fork: Bedrock Inference Profiles, Prompt Routers and Prompt Management (Optional) { #bedrock-inference-profiles-and-prompt-routers-optional }

**Environment Variables**: [`AWS_BEDROCK_ALLOW_CROSS_REGION_INFERENCE_PROFILE_ARN`](operations_configuration_bedrock.md#bedrock-allow-cross-region-profile-arn), [`AWS_BEDROCK_ALLOW_APPLICATION_INFERENCE_PROFILE_ARN`](operations_configuration_bedrock.md#bedrock-allow-application-profile-arn), [`AWS_BEDROCK_ALLOW_PROMPT_ROUTER_ARN`](operations_configuration_bedrock.md#bedrock-allow-prompt-router-arn), [`AWS_BEDROCK_ALLOW_PROMPT_ARN`](operations_configuration_bedrock.md#bedrock-allow-prompt-arn), [`AWS_BEDROCK_MODEL_ARN_MAPPING`](operations_configuration_bedrock.md#bedrock-model-arn-mapping)

Required only if you enable ARN-based routing features that allow users to pass inference profile, prompt router or Prompt Management prompt ARNs directly, or if you configure server-side ARN mappings.

??? example "Bedrock Inference Profiles, Prompt Routers and Prompt Management IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockInferenceProfilesAndPromptRouters",
      "Effect": "Allow",
      "Action": [
        "bedrock:GetInferenceProfile",
        "bedrock:GetPromptRouter"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BedrockPromptManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock:GetPrompt",
        "bedrock:RenderPrompt"
      ],
      "Resource": "arn:aws:bedrock:*:*:prompt/*"
    }
    ```

    `bedrock:GetPrompt` resolves the model bound to the prompt variant; `bedrock:RenderPrompt` is required because the prompt ARN is then sent to Bedrock as the invocation `modelId`.

    !!! note "When to Include"
        Add these permissions when:

        - `AWS_BEDROCK_ALLOW_CROSS_REGION_INFERENCE_PROFILE_ARN=true`
        - `AWS_BEDROCK_ALLOW_APPLICATION_INFERENCE_PROFILE_ARN=true`
        - `AWS_BEDROCK_ALLOW_PROMPT_ROUTER_ARN=true`
        - `AWS_BEDROCK_ALLOW_PROMPT_ARN=true` (`bedrock:GetPrompt` and `bedrock:RenderPrompt` only)
        - `AWS_BEDROCK_MODEL_ARN_MAPPING` is configured with any mappings

---

## :material-shield-check: Bedrock Guardrails (Optional)

**Environment Variables**: [`AWS_BEDROCK_GUARDRAIL_IDENTIFIER`](operations_configuration_bedrock.md#aws-bedrock-guardrail-identifier), [`AWS_BEDROCK_GUARDRAIL_VERSION`](operations_configuration_bedrock.md#aws-bedrock-guardrail-version)

Required if you configure Bedrock Guardrails for content filtering, use the `moderation` request parameter, or select a guardrail on the [Moderations API](api_openai_moderations.md) (without a guardrail, that API falls back to [Comprehend toxicity moderation](#comprehend-moderation)). See the [Bedrock Guardrails](operations_configuration_bedrock.md#bedrock-guardrails) configuration section.

??? example "Bedrock Guardrails IAM Policy Statement"
    ```json
    {
      "Sid": "BedrockGuardrails",
      "Effect": "Allow",
      "Action": [
        "bedrock:ApplyGuardrail"
      ],
      "Resource": "arn:aws:bedrock:*:*:guardrail/*"
    }
    ```

---

## :material-database-lock: Bedrock Session Storage (Optional)

**Environment Variables**: none (enabled by the `store=true` request parameter; see [Bedrock Session Storage](operations_configuration_bedrock.md#bedrock-session-storage-optional) configuration)

Required if clients use `store=true` on the [Responses](api_openai_responses.md#stored-responses) or [Chat Completions](api_openai_chat_completions.md#stored-chat-completions) APIs, or the [Conversations](api_openai_conversations.md) API, all of which persist state in Amazon Bedrock sessions.

??? example "Bedrock Session Storage IAM Policy Statement"
    ```json
    {
      "Sid": "BedrockSessionStorage",
      "Effect": "Allow",
      "Action": [
        "bedrock:CreateSession",
        "bedrock:GetSession",
        "bedrock:UpdateSession",
        "bedrock:CreateInvocation",
        "bedrock:PutInvocationStep",
        "bedrock:ListInvocations",
        "bedrock:ListInvocationSteps",
        "bedrock:GetInvocationStep",
        "bedrock:EndSession",
        "bedrock:DeleteSession",
        "bedrock:TagResource",
        "bedrock:ListTagsForResource"
      ],
      "Resource": "arn:aws:bedrock:*:*:session/*"
    },
    {
      "Sid": "BedrockSessionListing",
      "Effect": "Allow",
      "Action": "bedrock:ListSessions",
      "Resource": "*"
    }
    ```

    `bedrock:ListSessions` serves the stored chat completions listing endpoint (`GET /v1/chat/completions`); the account-level `ListSessions` action does not support resource scoping. `bedrock:GetSession` is used on deletion and `bedrock:ListTagsForResource` on both deletion and listing, to check that a stored object belongs to the API it is requested from. `bedrock:UpdateSession` serves the conversation metadata update (`POST /v1/conversations/{conversation_id}`) only.

    Add `kms:Encrypt`, `kms:Decrypt`, `kms:GenerateDataKey` and `kms:DescribeKey` on the key when [`AWS_BEDROCK_SESSION_ENCRYPTION_KEY_ARN`](operations_configuration_bedrock.md#aws-bedrock-session-encryption-key-arn) is configured — the set AWS documents for [session encryption](https://docs.aws.amazon.com/bedrock/latest/userguide/sessions-encryption.html). The [Terraform module](https://github.com/stdapi-ai/terraform-aws-stdapi-ai) grants a slightly different set, adding `kms:CreateGrant` and leaving out `kms:Encrypt`.

---

## :material-layers-triple: Bedrock Mantle (Optional) { #bedrock-mantle-iam }

**Environment Variables**: [`AWS_BEDROCK_MANTLE_ENABLED`](operations_configuration_aws.md#bedrock-mantle-enabled)

Required for [`AWS_BEDROCK_MANTLE_ENABLED`](operations_configuration_aws.md#bedrock-mantle-enabled) (enabled by default), which exposes models served by the Amazon Bedrock Mantle endpoint (OpenAI GPT, xAI Grok, Google Gemma, and more). Without these permissions the server still starts normally: Mantle models are not listed and a warning is logged.

??? example "Bedrock Mantle IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockMantleInference",
      "Effect": "Allow",
      "Action": [
        "bedrock-mantle:CreateInference",
        "bedrock-mantle:GetInference",
        "bedrock-mantle:DeleteInference",
        "bedrock-mantle:ListModels",
        "bedrock-mantle:GetModel",
        "bedrock-mantle:CancelInference",
        "bedrock-mantle:CountTokens"
      ],
      "Resource": "arn:aws:bedrock-mantle:*:*:project/*"
    },
    {
      "Sid": "BedrockMantleBearerToken",
      "Effect": "Allow",
      "Action": "bedrock-mantle:CallWithBearerToken",
      "Resource": "*"
    }
    ```

    `bedrock-mantle:CallWithBearerToken` authorizes the short-term bearer tokens the server derives from its AWS credential chain; it does not support resource scoping.

    `bedrock-mantle:CountTokens` serves [`/anthropic/v1/messages/count_tokens`](api_anthropic_messages.md) for a Mantle-served model: Amazon Bedrock's own `CountTokens` accepts Anthropic models only, so the count is proxied to the Mantle endpoint. Without it that route answers `500`.

---

## :material-web: Web Search (Optional) { #web-search-iam }

**Environment Variables**: none (enabled by a `web_search` tool in a request)

Required for the built-in [web search tool](api_openai_responses.md#openai-gpt-web-search) on the OpenAI GPT-5.x family, whichever settings are in use. Each action is authorized only when the model actually attempts that call, and a denied call does not fail the request: AWS documents the model continuing with the information it already has and telling you it could not retrieve enough current information ([Identity and access management for Web Search](https://docs.aws.amazon.com/bedrock/latest/userguide/security-web-search.html)).

!!! warning "A missing web search permission produces no error and no server log entry"
    The denial is handled inside the model call, so the request succeeds with a normal answer: the server sees nothing to report, and the response is indistinguishable from the model deciding it did not need to search. When answers never cite a source, check these permissions (and the Region the call was served in) before suspecting the model. AWS CloudTrail records the denied `bedrock-websearch` calls.

Add `bedrock-websearch:ExternalWebAccess` on top when a request can reach external web access — that is, when [`AWS_BEDROCK_EXTERNAL_WEB_ACCESS`](operations_configuration_models.md#bedrock-external-web-access) is enabled, or when [`AWS_BEDROCK_ALLOW_EXTERNAL_WEB_ACCESS_OVERRIDE`](operations_configuration_models.md#bedrock-allow-external-web-access-override) lets a client ask for it per request. Leaving it out is what keeps every search inside the AWS boundary.

??? example "Web Search IAM Policy Statement"
    ```json
    {
      "Sid": "BedrockWebSearch",
      "Effect": "Allow",
      "Action": [
        "bedrock-websearch:InvokeSearch",
        "bedrock-websearch:InvokeFetch"
      ],
      "Resource": "*"
    }
    ```

    `InvokeSearch` and `InvokeFetch` are authorized on AWS-owned tool resources (`arn:aws:bedrock-websearch:<region>:aws:tool/<name>`), which `"*"` covers; the AWS managed policies instead scope them to `arn:aws:bedrock-websearch:*:*:*`, and either form grants the same searches. `ExternalWebAccess` is a permission-only action with no resource of its own, so grant it with `"*"`. Web search runs in the Region that served the model call, in the [Regions where the tool is offered](api_openai_responses.md#openai-gpt-web-search); scope the statement with an `aws:RequestedRegion` condition to pin which Regions may run searches. See [Identity and access management for Web Search](https://docs.aws.amazon.com/bedrock/latest/userguide/security-web-search.html) and [Actions, resources, and condition keys](https://docs.aws.amazon.com/service-authorization/latest/reference/list_bedrock-websearch.html).

---

## :material-database: S3 File Storage (Optional)

**Environment Variables**: [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket), [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets)

Required for storing generated images, audio files, documents, and videos. See [Storage Configuration](operations_configuration_storage.md#storage-configuration) for bucket setup details.

??? example "S3 File Storage IAM Policy Statements"
    ```json
    {
      "Sid": "S3FileStorage",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectTagging",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::AWS_S3_BUCKET_VALUE/*"
    },
    {
      "Sid": "S3FileStorageList",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads"
      ],
      "Resource": "arn:aws:s3:::AWS_S3_BUCKET_VALUE"
    }
    ```

    !!! info "Replace Bucket Name"
        Replace `AWS_S3_BUCKET_VALUE` with the value of your [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket) environment variable. Repeat both statements for each [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets) bucket — they serve video generation, asynchronous embeddings (TwelveLabs Marengo, Amazon Nova), [large attachments](features.md#attachment-size) on any multimodal route, and [Speech-to-Text](#speech-to-text-optional) failover, and the Files API looks up objects across every configured bucket.

    !!! note "Multipart Uploads"
        Large files are uploaded and copied with the multipart API. Its `CreateMultipartUpload`, `UploadPart`, `UploadPartCopy`, and `CompleteMultipartUpload` operations have no dedicated IAM actions — they are authorized by `s3:PutObject` — which is why only the abort and listing actions appear above.

    !!! note "Cross-Region Access"
        Bucket ARNs are region-agnostic, so one statement per bucket covers every region. When a request fails over to another region, the server copies the object server-side through the destination region's S3 endpoint, reading the source bucket from there. Grant these actions on the source and destination buckets alike, and on the KMS key of each encrypted bucket.

    **If your S3 bucket uses KMS encryption**, also add:

    ```json
    {
      "Sid": "KMSEncryptedBucket",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "s3.REGION.amazonaws.com"
        }
      }
    }
    ```

    !!! tip "KMS Security"
        The `kms:ViaService` condition restricts KMS key usage to S3 service calls only, following AWS security best practices. Because the condition pins a single region, add one statement per region — with that region's key ARN and `s3.REGION.amazonaws.com` — when you use regional buckets with per-region keys.

---

## :material-bucket-outline: S3 Accepted Input Buckets (Optional) { #s3-accepted-input-buckets }

**Environment Variables**: [`AWS_S3_ACCEPTED_BUCKETS`](operations_configuration_storage.md#aws-s3-accepted-buckets)

Required when clients send S3 URIs — or S3 HTTP URLs, including presigned ones — that point at buckets this deployment does not own. The server reads those objects with its own role: a bucket that is not declared is refused before any AWS call, and a declared bucket the role cannot read answers `400` naming that input.

??? example "S3 Accepted Input Buckets IAM Policy Statements"
    ```json
    {
      "Sid": "S3AcceptedBuckets",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": [
        "arn:aws:s3:::ACCEPTED_BUCKET_NAME/*"
      ]
    }
    ```

    !!! info "Replace the Bucket Names"
        Replace `ACCEPTED_BUCKET_NAME` with a bucket name declared in [`AWS_S3_ACCEPTED_BUCKETS`](operations_configuration_storage.md#aws-s3-accepted-buckets), and list one `arn:aws:s3:::BUCKET/*` resource per entry of that map. Grant it on the objects only — the server reads the object a request names and never lists these buckets, so no `s3:ListBucket` is needed.

    !!! note "Reads, Heads, and Copies"
        `s3:GetObject` covers all three ways the server touches these objects: reading the bytes, a `HeadObject` for the size and content type, and the server-side copy that moves an input into the region a model runs in. The destination of that copy is one of the deployment's own buckets, already covered by [S3 File Storage](#s3-file-storage-optional).

    !!! note "The bucket owner grants the other half"
        These buckets are not the deployment's, so their own bucket policy must also allow this role to `s3:GetObject` — cross-account access needs both sides. A denial that survives this statement is the caller's object to fix.

    **If an accepted bucket uses KMS encryption**, also add:

    ```json
    {
      "Sid": "KMSAcceptedBuckets",
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": [
        "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID"
      ],
      "Condition": {
        "StringLike": {
          "kms:ViaService": "s3.*.amazonaws.com"
        }
      }
    }
    ```

    !!! tip "KMS Security"
        Only `kms:Decrypt` is granted — the server never writes to these buckets, so it never needs `kms:GenerateDataKey` on their keys. The `kms:ViaService` condition restricts the key to S3 service calls; it is a `StringLike` because accepted buckets may span regions. When every key lives in one region, tighten it to `StringEquals` on `s3.REGION.amazonaws.com`. List one key ARN per encrypted bucket, and, for a key in another account, its key policy must grant this role as well.

---

## :material-magnify: Vector Stores (Optional) { #vector-stores-optional }

**Environment Variables**: [`AWS_S3_VECTORS_BUCKET`](operations_configuration_storage.md#aws-s3-vectors-bucket), [`AWS_S3_VECTORS_REGION`](operations_configuration_storage.md#aws-s3-vectors-region), [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket)

Required by the [Vector Stores API](api_openai_vector_stores.md). The indexed content lives in an [Amazon S3 vector bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html) you create; the stores' own records live in the general purpose bucket under [`AWS_S3_VECTOR_STORES_PREFIX`](operations_configuration_storage.md#aws-s3-vector-stores-prefix) and are covered by the [S3 File Storage](#s3-file-storage-optional) statements above.

??? example "Vector Stores IAM Policy Statements"
    ```json
    {
      "Sid": "VectorStoreIndexes",
      "Effect": "Allow",
      "Action": [
        "s3vectors:CreateIndex",
        "s3vectors:DeleteIndex",
        "s3vectors:PutVectors",
        "s3vectors:GetVectors",
        "s3vectors:QueryVectors",
        "s3vectors:DeleteVectors"
      ],
      "Resource": [
        "arn:aws:s3vectors:REGION:ACCOUNT_ID:bucket/AWS_S3_VECTORS_BUCKET_VALUE",
        "arn:aws:s3vectors:REGION:ACCOUNT_ID:bucket/AWS_S3_VECTORS_BUCKET_VALUE/index/*"
      ]
    }
    ```

    !!! info "Replace the Placeholders"
        Replace `AWS_S3_VECTORS_BUCKET_VALUE` with your [`AWS_S3_VECTORS_BUCKET`](operations_configuration_storage.md#aws-s3-vectors-bucket) value, `REGION` with [`AWS_S3_VECTORS_REGION`](operations_configuration_storage.md#aws-s3-vectors-region), and `ACCOUNT_ID` with your account. The bucket ARN itself is needed for the index actions; the index ARN pattern covers the per-store indexes the gateway creates and deletes.

    !!! note "The bucket is yours to create"
        The gateway never creates or deletes the vector bucket, only the indexes inside it, so no bucket-level create or delete action is granted.

    !!! note "Records live in the general purpose bucket"
        Grant the [S3 File Storage](#s3-file-storage-optional) statements on [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket) as well: the stores, their attached files and their batches are JSON objects there.

    **If your vector bucket uses KMS encryption**, also add:

    ```json
    {
      "Sid": "KMSVectorBucket",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "s3vectors.REGION.amazonaws.com"
        }
      }
    }
    ```

    !!! tip "KMS Security"
        `REGION` is [`AWS_S3_VECTORS_REGION`](operations_configuration_storage.md#aws-s3-vectors-region) — the region the vector bucket lives in — in the key ARN and in the `kms:ViaService` value alike. That condition restricts the key to Amazon S3 Vectors calls, so the role cannot use it anywhere else. Add this statement for a bucket you encrypted with a customer managed key of your own.

---

## :material-tray-arrow-down: Durable Vector Store Indexing (Optional) { #durable-vector-store-indexing }

**Environment Variables**: [`AWS_SQS_VECTOR_STORE_QUEUE_URL`](operations_configuration_storage.md#aws-sqs-vector-store-queue-url)

Required to keep indexing a vector store file when the server that accepted it stops. The gateway both writes the work to the [Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html) queue you create and reads it back, so it needs the producer and the consumer actions on that one queue.

??? example "Durable Vector Store Indexing IAM Policy Statements"
    ```json
    {
      "Sid": "VectorStoreIndexingQueue",
      "Effect": "Allow",
      "Action": [
        "sqs:SendMessage",
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:ChangeMessageVisibility",
        "sqs:GetQueueAttributes"
      ],
      "Resource": "arn:aws:sqs:REGION:ACCOUNT_ID:QUEUE_NAME"
    }
    ```

    !!! info "Replace the Placeholders"
        `REGION`, `ACCOUNT_ID` and `QUEUE_NAME` are the three parts of your [`AWS_SQS_VECTOR_STORE_QUEUE_URL`](operations_configuration_storage.md#aws-sqs-vector-store-queue-url). Grant this on the queue ARN itself — never on `*`.

    !!! note "The queues are yours to create"
        The gateway never creates, deletes or reconfigures a queue, so no `sqs:CreateQueue`, `sqs:DeleteQueue` or `sqs:SetQueueAttributes` is granted. `sqs:GetQueueAttributes` is read-only and is what lets the gateway honour your dead-letter queue's redrive policy.

    !!! note "The dead-letter queue needs nothing"
        Amazon SQS moves an exhausted message itself; the gateway never reads the dead-letter queue, so grant it nothing.

    **If your queue uses SSE-KMS with a key of your own**, also add:

    ```json
    {
      "Sid": "KMSVectorStoreIndexingQueue",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "sqs.REGION.amazonaws.com"
        }
      }
    }
    ```

    !!! tip "KMS Security"
        Amazon SQS calls AWS KMS under the gateway's own identity, so the grant is conditioned on the call arriving through Amazon SQS in the region the queue lives in — the `REGION` of your [`AWS_SQS_VECTOR_STORE_QUEUE_URL`](operations_configuration_storage.md#aws-sqs-vector-store-queue-url), in the key ARN and in the `kms:ViaService` value alike. Both actions are needed: `kms:GenerateDataKey` to send a message, `kms:Decrypt` to receive one. A queue encrypted with the Amazon SQS managed key needs no statement.

---

## :material-table: Shared Table (Optional) { #shared-table }

**Environment Variables**: [`AWS_DYNAMODB_TABLE`](operations_configuration_storage.md#aws-dynamodb-table), [`AWS_DYNAMODB_REGION`](operations_configuration_storage.md#aws-dynamodb-region), [`MODEL_CACHE_SHARED`](operations_configuration_models.md#model-cache-shared), [`TENANT_RATE_LIMIT_REQUESTS_PER_MINUTE`](operations_configuration_authentication.md#tenant-rate-limit-requests-per-minute), [`TENANT_RATE_LIMIT_TOKENS_PER_MINUTE`](operations_configuration_authentication.md#tenant-rate-limit-tokens-per-minute)

Required by the features whose records every instance of a deployment reads and writes, on the one [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) table you create. Grant it on that table's ARN. [Model list sharing](operations_resilience.md#model-list-refresh), [tenant API keys](operations_authentication_security.md#tenant-api-keys) and their [rate limits](operations_authentication_security.md#tenant-rate-limits) are the features that use it; a server missing these permissions reports it at `WARNING` and keeps discovering the model list itself, while tenant keys fail closed.

??? example "Shared Table IAM Policy Statements"
    ```json
    {
      "Sid": "SharedTable",
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:DeleteItem",
        "dynamodb:Query",
        "dynamodb:DescribeTable",
        "dynamodb:DescribeTimeToLive"
      ],
      "Resource": "arn:aws:dynamodb:REGION:ACCOUNT_ID:table/TABLE_NAME"
    },
    {
      "Sid": "SharedTableRateLimitCounters",
      "Effect": "Allow",
      "Action": "dynamodb:UpdateItem",
      "Resource": "arn:aws:dynamodb:REGION:ACCOUNT_ID:table/TABLE_NAME",
      "Condition": {
        "ForAllValues:StringLike": { "dynamodb:LeadingKeys": ["LIMIT#*"] }
      }
    },
    {
      "Sid": "SharedTableKms",
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID",
      "Condition": {
        "StringEquals": { "kms:ViaService": "dynamodb.REGION.amazonaws.com" }
      }
    }
    ```

    !!! info "Replace the Placeholders"
        `REGION` is [`AWS_DYNAMODB_REGION`](operations_configuration_storage.md#aws-dynamodb-region), `ACCOUNT_ID` your AWS account ID, and `TABLE_NAME` your [`AWS_DYNAMODB_TABLE`](operations_configuration_storage.md#aws-dynamodb-table). Grant this on the table ARN itself — never on `*`.

    !!! note "The table is yours to create"
        The gateway never creates, deletes or reconfigures a table, so no `dynamodb:CreateTable`, `dynamodb:DeleteTable` or `dynamodb:UpdateTable` is granted. `dynamodb:DescribeTable` and `dynamodb:DescribeTimeToLive` are read-only and are what let the gateway report a table whose key schema or expiration is not what the features need.

    !!! note "No index and no scan"
        The table has no secondary index, so no index ARN is needed, and every read is addressed by key — `dynamodb:Scan` is deliberately not granted.

    !!! note "The counter statement is only needed with rate limits"
        `dynamodb:UpdateItem` is the one action that changes an item in place, and the [per-tenant rate limits](operations_authentication_security.md#tenant-rate-limits) are its only user: the counters live in the items whose partition key starts with `LIMIT#`, and the [`dynamodb:LeadingKeys`](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/specifying-conditions.html) condition keeps the grant to those, so it can never rewrite a tenant record or the shared model list. Omit the statement when no tenant is rate limited; a server that is asked to enforce a limit without it reports the missing action at startup and refuses the limited tenants' requests with `503` rather than serving them unlimited.

    !!! note "If the table uses a customer managed key"
        Amazon DynamoDB decrypts the table's key as the caller, so a table encrypted with a customer managed AWS KMS key whose policy delegates to IAM needs the `SharedTableKms` statement, with `KEY_ID` that key: without it every read and write is refused with `AccessDenied` on `kms:Decrypt`. Omit it for the default AWS owned key, which is free and needs no permission. Encryption at rest is always on.

    !!! warning "Write access to the table is control of what the gateway serves"
        The published model list carries the routing state the gateway invokes with — inference profiles and Amazon Bedrock Marketplace and Amazon SageMaker AI endpoint ARNs — so anything that can write to this table can decide where the gateway sends inference traffic. Treat `dynamodb:PutItem` on it as equivalent to the gateway's own inference permissions: grant it to the gateway's task role only, keep the table dedicated to the gateway, and scope the inference permissions above to the endpoint ARNs you actually deploy.

---

## :material-account-key: Tenant API Key Delivery (Optional) { #tenant-key-delivery }

**Environment Variables**: [`TENANT_API_KEYS`](operations_configuration_authentication.md#tenant-api-keys), [`TENANT_KEY_SSM_PARAMETER_PREFIX`](operations_configuration_authentication.md#tenant-key-ssm-parameter-prefix), [`TENANT_KEY_SSM_KMS_KEY_ID`](operations_configuration_authentication.md#tenant-key-ssm-kms-key-id)

Required, together with the [shared table permissions](#shared-table), when [tenant API keys](operations_authentication_security.md#tenant-api-keys) are enabled and keys are delivered through Parameter Store — the default. A deployment that sets [`TENANT_KEY_SECRETSMANAGER_PREFIX`](operations_configuration_authentication.md#tenant-key-secretsmanager-prefix) needs the [rotation statements](#tenant-key-rotation) instead, and none of these. The gateway writes each minted key exactly once (`PutParameter` refuses to overwrite), and reads a parameter back only to recover a mint that crashed between delivery and recording. Grant it on the delivery prefix and nothing wider.

??? example "Tenant Key Delivery IAM Policy Statement"
    ```json
    {
      "Sid": "TenantKeyDelivery",
      "Effect": "Allow",
      "Action": [
        "ssm:PutParameter",
        "ssm:GetParameter"
      ],
      "Resource": "arn:aws:ssm:REGION:ACCOUNT_ID:parameter/PREFIX/*"
    }
    ```

    !!! info "Replace the Placeholders"
        `REGION` is the deployment's own Region, `ACCOUNT_ID` your AWS account ID, and `/PREFIX` your [`TENANT_KEY_SSM_PARAMETER_PREFIX`](operations_configuration_authentication.md#tenant-key-ssm-parameter-prefix) — the parameter ARN concatenates `parameter` and the prefix's leading slash.

    !!! note "One prefix per deployment"
        Any principal allowed to read under the prefix can read every tenant's key, and the gateway role itself can read them back — unless [`TENANT_KEY_SSM_KMS_KEY_ID`](operations_configuration_authentication.md#tenant-key-ssm-kms-key-id) names a key of your own, which also takes `kms:Decrypt` on it. Keep the prefix private to one deployment, and delete each parameter once its key is delivered — the gateway never needs it again.

??? example "Customer Managed Key Statement (with `TENANT_KEY_SSM_KMS_KEY_ID`)"
    Add this statement when the delivery parameters are encrypted with a key of your own instead of the AWS-managed `alias/aws/ssm` key. `kms:Encrypt` covers writing a standard `SecureString`, `kms:Decrypt` covers reading one back, and `kms:GenerateDataKey` is only needed if the account's default parameter tier creates advanced parameters. The `kms:ViaService` condition keeps the grant usable through Parameter Store alone.

    ```json
    {
      "Sid": "TenantKeyDeliveryKms",
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "ssm.REGION.amazonaws.com"
        }
      }
    }
    ```

    !!! info "Replace the Placeholders"
        `REGION` is the deployment's own Region, `ACCOUNT_ID` your AWS account ID, and `KEY_ID` the key's own identifier. `Resource` is always the key ARN, even where `TENANT_KEY_SSM_KMS_KEY_ID` names the key by alias: KMS does not accept an alias ARN as the resource of a cryptographic action.

---

## :material-key-change: Tenant API Key Rotation (Optional) { #tenant-key-rotation }

**Environment Variables**: [`TENANT_KEY_SECRETSMANAGER_PREFIX`](operations_configuration_authentication.md#tenant-key-secretsmanager-prefix), [`TENANT_KEY_SECRETSMANAGER_KMS_KEY_ID`](operations_configuration_authentication.md#tenant-key-secretsmanager-kms-key-id), [`TENANT_KEY_ROTATION_DAYS`](operations_configuration_authentication.md#tenant-key-rotation-days)

Required, together with the [shared table permissions](#shared-table), when tenant keys are [stored in AWS Secrets Manager](operations_authentication_security.md#rotating-tenant-keys) — it replaces the [Parameter Store delivery](#tenant-key-delivery) statements, which are then not needed. The gateway creates a tenant's secret when none exists, writes each minted or rotated key as a version of it, reads a version back only to recover a write another instance or a crashed pass made first, and moves the `AWSCURRENT` label onto the new version. It never deletes a secret and never tags one: the secret's lifecycle and tags are yours, or the Terraform module's. Grant it on the secret prefix and nothing wider — a secret's ARN ends with a random suffix, so the wildcard after the prefix is what matches it.

??? example "Tenant Key Rotation IAM Policy Statement"
    ```json
    {
      "Sid": "TenantKeyRotation",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:CreateSecret",
        "secretsmanager:DescribeSecret",
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue",
        "secretsmanager:UpdateSecretVersionStage"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:PREFIX/*"
    }
    ```

    !!! info "Replace the Placeholders"
        `REGION` is the deployment's own Region, `ACCOUNT_ID` your AWS account ID, and `PREFIX` your [`TENANT_KEY_SECRETSMANAGER_PREFIX`](operations_configuration_authentication.md#tenant-key-secretsmanager-prefix).

    !!! note "One prefix per deployment"
        Any principal allowed to read under the prefix can read every tenant's key — unless [`TENANT_KEY_SECRETSMANAGER_KMS_KEY_ID`](operations_configuration_authentication.md#tenant-key-secretsmanager-kms-key-id) names a key of your own, which also takes `kms:Decrypt` on it. Keep the prefix private to one deployment, and grant each tenant `secretsmanager:GetSecretValue` on its own secret alone.

??? example "Customer Managed Key Statement (with `TENANT_KEY_SECRETSMANAGER_KMS_KEY_ID`)"
    Add this statement when the secrets are encrypted with a key of your own instead of the AWS-managed `alias/aws/secretsmanager` key. `kms:GenerateDataKey` covers writing a version, `kms:Decrypt` covers reading one back. The `kms:ViaService` condition keeps the grant usable through Secrets Manager alone, and the encryption-context condition narrows it to the tenant secrets rather than every secret the account encrypts under the key.

    ```json
    {
      "Sid": "TenantKeyRotationKms",
      "Effect": "Allow",
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "secretsmanager.REGION.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:PREFIX/*"
        }
      }
    }
    ```

    !!! info "Replace the Placeholders"
        `REGION` is the deployment's own Region, `ACCOUNT_ID` your AWS account ID, `KEY_ID` the key's own identifier and `PREFIX` your secret prefix. `Resource` is always the key ARN, even where `TENANT_KEY_SECRETSMANAGER_KMS_KEY_ID` names the key by alias: KMS does not accept an alias ARN as the resource of a cryptographic action.

---

## :material-account-key: Tenant AWS Credentials (Optional) { #tenant-aws-credentials }

**Environment Variables**: [`TENANT_AWS_CREDENTIALS`](operations_configuration_authentication.md#tenant-aws-credentials)

Required when [tenant AWS credentials](operations_authentication_security.md#tenant-aws-credentials) are enabled: the gateway assumes each tenant's registered cross-account role to run that tenant's model invocations under the tenant's own account. Grant `sts:AssumeRole` on the tenant roles alone — list them, or constrain a pattern — never on `*`, and require an `ExternalId` to be presented so no code path can ever assume a role without the confused-deputy check.

??? example "Tenant Role Assumption IAM Policy Statement"
    ```json
    {
      "Sid": "TenantRoleAssumption",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::TENANT_ACCOUNT_ID:role/TENANT_ROLE_NAME"
      ],
      "Condition": {
        "StringLike": { "sts:ExternalId": "?*" }
      }
    }
    ```

    !!! info "The other half lives in the tenant's account"
        Each tenant role's **trust policy** must allow this deployment's account (or role) to call `sts:AssumeRole` on it, conditioned on the `ExternalId` the gateway minted for that tenant — the shape is shown in [Tenant AWS credentials](operations_authentication_security.md#tenant-aws-credentials). The role's permission policy is the tenant's to scope: the Bedrock invocation actions on the models it wants to serve.

---

## :material-book-search: Knowledge Base Vector Stores (Optional) { #knowledge-base-vector-stores }

**Environment Variables**: [`AWS_BEDROCK_KNOWLEDGE_BASE_IDS`](operations_configuration_storage.md#aws-bedrock-knowledge-base-ids)

Required to serve an [Amazon Bedrock knowledge base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) you created as a [vector store](api_openai_vector_stores.md#knowledge-base-stores). Grant one statement per allowlisted knowledge base, on its own ARN.

??? example "Knowledge Base Vector Stores IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockKnowledgeBaseVectorStores",
      "Effect": "Allow",
      "Action": [
        "bedrock:GetKnowledgeBase",
        "bedrock:Retrieve",
        "bedrock:ListDataSources",
        "bedrock:IngestKnowledgeBaseDocuments",
        "bedrock:ListKnowledgeBaseDocuments",
        "bedrock:GetKnowledgeBaseDocuments",
        "bedrock:DeleteKnowledgeBaseDocuments"
      ],
      "Resource": "arn:aws:bedrock:REGION:ACCOUNT_ID:knowledge-base/KNOWLEDGE_BASE_ID"
    }
    ```

    !!! info "Replace the Placeholders"
        Replace `REGION` with the first [`AWS_BEDROCK_REGIONS`](operations_configuration_aws.md#aws-bedrock-regions) entry, `ACCOUNT_ID` with your account, and `KNOWLEDGE_BASE_ID` with the knowledge base identifier — one ARN per entry of [`AWS_BEDROCK_KNOWLEDGE_BASE_IDS`](operations_configuration_storage.md#aws-bedrock-knowledge-base-ids).

    !!! note "No discovery action, deliberately"
        `bedrock:ListKnowledgeBases` is **not** granted, and is not needed: the server never discovers knowledge bases it was not given. Only the identifiers in the allowlist are ever addressed, and any other one is answered as an unknown vector store.

    !!! note "The knowledge base is yours to create"
        The gateway never creates or deletes a knowledge base, so no create, update or delete action on the knowledge base itself is granted — only the documents of its data source.

    !!! tip "Checked once at startup"
        `bedrock:GetKnowledgeBase` — already needed to serve a store — is also called on every allowlisted entry at startup, to confirm each one is a kind the server can serve. No extra action is required for that check, and a role missing the action never stops the server: it starts with one warning per entry instead.

---

## :material-video: Video Generation (Optional) { #video-generation-optional }

**Environment Variables**: [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets)

Video generation itself runs on the core Bedrock asynchronous invocation permissions (`bedrock:InvokeModel`, `bedrock:GetAsyncInvoke`, `bedrock:TagResource`) plus [S3 File Storage](#s3-file-storage-optional) permissions on each regional bucket. The video job listing endpoint (`GET /v1/videos`) additionally requires:

??? example "Video Job Listing IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockVideoJobListing",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListAsyncInvokes"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BedrockVideoJobTags",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListTagsForResource"
      ],
      "Resource": "arn:aws:bedrock:*:*:async-invoke/*"
    }
    ```

    The account-level `ListAsyncInvokes` action does not support resource scoping; `ListTagsForResource` reads the job metadata tags used to attribute listed jobs.

---

## :material-package-variant-closed: Batch Inference (Optional) { #batch-inference }

**Environment Variables**: [`AWS_BEDROCK_BATCH_ROLE_ARN`](operations_configuration_bedrock.md#aws-bedrock-batch-role-arn), [`AWS_S3_BATCHES_PREFIX`](operations_configuration_storage.md#aws-s3-batches-prefix), [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket), [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets)

The [Batch API](api_openai_batches.md) and the [Message Batches API](api_anthropic_batches.md) run on [Amazon Bedrock batch inference](https://docs.aws.amazon.com/bedrock/latest/userguide/batch-inference.html), which needs **two** policies: the server's own, and a service role Amazon Bedrock assumes to read the requests and write the results.

### The Server's Policy

??? example "Batch Inference IAM Policy Statements"
    ```json
    {
      "Sid": "BedrockBatchJobs",
      "Effect": "Allow",
      "Action": [
        "bedrock:CreateModelInvocationJob",
        "bedrock:GetModelInvocationJob",
        "bedrock:StopModelInvocationJob"
      ],
      "Resource": "arn:aws:bedrock:*:<account-id>:model-invocation-job/*"
    },
    {
      "Sid": "BedrockBatchPassRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::<account-id>:role/stdapi-ai-batch",
      "Condition": {
        "StringEquals": {"iam:PassedToService": "bedrock.amazonaws.com"}
      }
    }
    ```

    Substitute `<account-id>` with your AWS account ID, and the role ARN with the value of `AWS_BEDROCK_BATCH_ROLE_ARN`. The server also needs the [S3 File Storage](#s3-file-storage-optional) permissions on every bucket a batch may use.

### The Service Role

Create a role named by `AWS_BEDROCK_BATCH_ROLE_ARN` whose trust policy lets Amazon Bedrock assume it, scoped to your account and to batch jobs so it cannot be used by another account's jobs:

??? example "Batch Service Role Trust Policy"
    ```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {"Service": "bedrock.amazonaws.com"},
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {"aws:SourceAccount": "<account-id>"},
            "ArnEquals": {
              "aws:SourceArn": "arn:aws:bedrock:*:<account-id>:model-invocation-job/*"
            }
          }
        }
      ]
    }
    ```

??? example "Batch Service Role Permissions Policy"
    ```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "BatchDataAccess",
          "Effect": "Allow",
          "Action": ["s3:GetObject", "s3:PutObject"],
          "Resource": "arn:aws:s3:::<bucket-name>/batches/*"
        },
        {
          "Sid": "BatchDataListing",
          "Effect": "Allow",
          "Action": "s3:ListBucket",
          "Resource": "arn:aws:s3:::<bucket-name>",
          "Condition": {"StringLike": {"s3:prefix": "batches/*"}}
        },
        {
          "Sid": "BatchModelInvocation",
          "Effect": "Allow",
          "Action": "bedrock:InvokeModel",
          "Resource": [
            "arn:aws:bedrock:*::foundation-model/*",
            "arn:aws:bedrock:*:<account-id>:inference-profile/*"
          ]
        }
      ]
    }
    ```

    Repeat the S3 statements for each `AWS_S3_REGIONAL_BUCKETS` bucket, and substitute `batches/` with your `AWS_S3_BATCHES_PREFIX`. A cross-region inference profile needs `bedrock:InvokeModel` on **both** the profile and the foundation models behind it — see [Inference Profiles](#bedrock-inference-profiles-and-prompt-routers-optional).

---

## :material-account-voice: Text-to-Speech (Optional) { #text-to-speech-optional }

**Environment Variables**: [`AWS_POLLY_REGION`](operations_configuration_aws.md#aws-polly-region), [`DEFAULT_TTS_MODEL`](operations_configuration_bedrock.md#default-tts-model), [`DEFAULT_TTS_LANGUAGE`](operations_configuration_bedrock.md#default-tts-language), [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket), [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets)

Required for generating speech from text using Amazon Polly. See the [Audio and Text-to-Speech](operations_configuration_bedrock.md#audio-and-text-to-speech) configuration section.

!!! tip "Optimize Performance"
    Set [`DEFAULT_TTS_LANGUAGE`](operations_configuration_bedrock.md#default-tts-language) to skip language detection and avoid Amazon Comprehend API calls, improving response times and reducing costs.

??? example "Polly Text-to-Speech IAM Policy Statements"
    ```json
    {
      "Sid": "PollyTextToSpeech",
      "Effect": "Allow",
      "Action": [
        "polly:SynthesizeSpeech",
        "polly:StartSpeechSynthesisStream",
        "polly:DescribeVoices",
        "polly:StartSpeechSynthesisTask",
        "polly:GetSpeechSynthesisTask"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PollyS3Storage",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::AWS_S3_BUCKET_VALUE/*"
    }
    ```

    !!! info "Only for Long Input"
        The two task actions and the S3 statement serve [input above 3,000 characters](api_openai_audio_speech.md#long-input), which Amazon Polly synthesizes into a bucket co-located with the serving region.

        Replace `AWS_S3_BUCKET_VALUE` with the value of your [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket) environment variable, and repeat the statement for each [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets) bucket serving a Polly region. Amazon Polly writes the audio object with the identity that started the synthesis, which is why `s3:PutObject` belongs to this policy; the audio is then read back and deleted once the response has been sent.

    !!! warning "Granting the permissions is not what enables long input"
        The 3,000-character limit is decided by the configuration, not by this policy: text-to-speech stays capped at 3,000 characters per request — and requests above it are rejected with that limit — as long as no bucket is configured for the Polly regions ([`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket), [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets)).

        With a bucket configured but these actions missing, long requests are accepted and then fail on a permission error instead. Grant the whole set, or leave the bucket unconfigured.

    **If your S3 buckets use KMS encryption**, also add the KMS permissions for each bucket's key, with that region's `kms:ViaService` value.

---

## :material-microphone: Speech-to-Text (Optional) { #speech-to-text-optional }

**Environment Variables**: [`AWS_TRANSCRIBE_REGION`](operations_configuration_aws.md#aws-transcribe-region), [`AWS_TRANSCRIBE_S3_BUCKET`](operations_configuration_storage.md#aws-transcribe-s3-bucket), [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets), [`AWS_TRANSCRIBE_OUTPUT_ENCRYPTION_KEY_ARN`](operations_configuration_storage.md#aws-transcribe-output-encryption-key-arn)

Required for transcribing audio files using Amazon Transcribe. Each transcription job stages its audio in a bucket co-located with the Transcribe endpoint, so the S3 statement must cover every bucket that serves a candidate region.

??? example "Transcribe Speech-to-Text IAM Policy Statements"
    ```json
    {
      "Sid": "TranscribeSpeechToText",
      "Effect": "Allow",
      "Action": [
        "transcribe:StartTranscriptionJob",
        "transcribe:GetTranscriptionJob",
        "transcribe:DeleteTranscriptionJob",
        "transcribe:StartStreamTranscription"
      ],
      "Resource": "*"
    },
    {
      "Sid": "TranscribeMedical",
      "Effect": "Allow",
      "Action": [
        "transcribe:StartMedicalTranscriptionJob",
        "transcribe:StartMedicalStreamTranscription"
      ],
      "Resource": "*"
    },
    {
      "Sid": "TranscribeMedicalJobs",
      "Effect": "Allow",
      "Action": [
        "transcribe:GetMedicalTranscriptionJob",
        "transcribe:DeleteMedicalTranscriptionJob"
      ],
      "Resource": "arn:aws:transcribe:*:*:medical-transcription-job/*"
    },
    {
      "Sid": "TranscribeTagging",
      "Effect": "Allow",
      "Action": [
        "transcribe:TagResource"
      ],
      "Resource": [
        "arn:aws:transcribe:*:*:transcription-job/*",
        "arn:aws:transcribe:*:*:medical-transcription-job/*"
      ]
    },
    {
      "Sid": "TranscribeS3Storage",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectTagging",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::AWS_TRANSCRIBE_S3_BUCKET_VALUE/*"
    }
    ```

    !!! info "Replace Bucket Name"
        Replace `AWS_TRANSCRIBE_S3_BUCKET_VALUE` with the value of your [`AWS_TRANSCRIBE_S3_BUCKET`](operations_configuration_storage.md#aws-transcribe-s3-bucket) environment variable (or [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket) if using the same bucket).

    !!! note "One Bucket per Candidate Region"
        With the default multi-region behavior ([`AWS_TRANSCRIBE_REGION`](operations_configuration_aws.md#aws-transcribe-region) unset), Transcribe fails over across the [`AWS_BEDROCK_REGIONS`](operations_configuration_aws.md#aws-bedrock-regions) that have a co-located bucket: the primary region uses the bucket above, the others their [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets) entry. Repeat the `TranscribeS3Storage` statement for each of those buckets.

        On failover the audio is server-side copied from the previous candidate's bucket to the next one, which is why the copy and multipart actions are required. Set `AWS_TRANSCRIBE_REGION` to pin a single region and keep a single bucket.

    !!! info "`StartStreamTranscription` needs no bucket"
        `transcribe:StartStreamTranscription` serves [`stream=true`](api_openai_audio_transcriptions.md#streaming) requests, which send their audio to Transcribe directly instead of staging it. A deployment with no bucket at all still serves those, and only those — the `TranscribeS3Storage` statement above is what the other requests need.

    !!! info "Medical transcription"
        The `TranscribeMedical` and `TranscribeMedicalJobs` statements serve [`amazon.transcribe-medical`](api_openai_audio_transcriptions.md#medical-transcription) only; omit them from a hand-written policy to leave that model unavailable (the Terraform module grants them wherever it grants transcription). Its jobs use the same buckets and `TranscribeS3Storage` statement. The two `Start` actions accept no resource type, hence `"*"`; `transcribe:TagResource` covers the job tags sent at start.

    **If your transcribe S3 buckets use KMS encryption**, also add the KMS permissions for each bucket's key, with that region's `kms:ViaService` value.

**Encrypting the transcription output with your own key** ([`AWS_TRANSCRIBE_OUTPUT_ENCRYPTION_KEY_ARN`](operations_configuration_storage.md#aws-transcribe-output-encryption-key-arn)) additionally requires:

??? example "Transcribe Output Encryption IAM Policy Statement"
    ```json
    {
      "Sid": "TranscribeOutputEncryption",
      "Effect": "Allow",
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "AWS_TRANSCRIBE_OUTPUT_ENCRYPTION_KEY_ARN_VALUE"
    }
    ```

    !!! info "Replace Key ARN"
        Replace `AWS_TRANSCRIBE_OUTPUT_ENCRYPTION_KEY_ARN_VALUE` with the value of your [`AWS_TRANSCRIBE_OUTPUT_ENCRYPTION_KEY_ARN`](operations_configuration_storage.md#aws-transcribe-output-encryption-key-arn) environment variable. The key policy must allow the same actions for this role; `kms:Decrypt` is what lets the finished transcript be read back.

---

## :material-earth: Language Detection (Optional)

**Environment Variables**: [`AWS_COMPREHEND_REGION`](operations_configuration_aws.md#aws-comprehend-region)

Required for automatic language detection (used by TTS for voice selection).

??? example "Comprehend Language Detection IAM Policy Statement"
    ```json
    {
      "Sid": "ComprehendLanguageDetection",
      "Effect": "Allow",
      "Action": [
        "comprehend:DetectDominantLanguage"
      ],
      "Resource": "*"
    }
    ```

---

## :material-shield-alert: Comprehend Moderation (Optional) { #comprehend-moderation }

**Environment Variables**: [`AWS_COMPREHEND_REGION`](operations_configuration_aws.md#aws-comprehend-region)

Required for the [Moderations API](api_openai_moderations.md) toxicity backend — the default backend when no Bedrock guardrail is configured, and always available as the `amazon.comprehend-toxicity` model.

??? example "Comprehend Moderation IAM Policy Statement"
    ```json
    {
      "Sid": "ComprehendModeration",
      "Effect": "Allow",
      "Action": [
        "comprehend:DetectToxicContent"
      ],
      "Resource": "*"
    }
    ```

---

## :material-translate: Text Translation (Optional)

**Environment Variables**: [`AWS_TRANSLATE_REGION`](operations_configuration_aws.md#aws-translate-region)

Required for text translation features.

??? example "Translate Text Translation IAM Policy Statement"
    ```json
    {
      "Sid": "TranslateTextTranslation",
      "Effect": "Allow",
      "Action": [
        "translate:TranslateText",
        "translate:ListLanguages"
      ],
      "Resource": "*"
    }
    ```

    !!! note "`translate:ListLanguages`"
        Read once at startup, to refuse a language Amazon Translate does not support before the audio is transcribed. Without it translation still works: an unsupported language is then reported once the translation call itself fails.

---

## :material-cash-multiple: Cost Tracking (Optional) { #cost-tracking-iam }

**Environment Variables**: [`COST_TRACKING`](operations_configuration_observability.md#cost-tracking)

Required for [`COST_TRACKING`](operations_configuration_observability.md#cost-tracking) (disabled by default), which prices requests from the AWS Price List API. Without this permission the catalog stays empty and request logs carry no cost data.

??? example "Cost Tracking IAM Policy Statement"
    ```json
    {
      "Sid": "PricingCatalog",
      "Effect": "Allow",
      "Action": [
        "pricing:GetProducts"
      ],
      "Resource": "*"
    }
    ```

---

## :material-chart-timeline-variant: Usage API (Optional) { #usage-api-iam }

**Environment Variables**: [`USAGE_API`](operations_configuration_observability.md#usage-api)

Required only when [`USAGE_API`](operations_configuration_observability.md#usage-api) is enabled (disabled by default), which serves the [organization usage and costs endpoints](api_openai_organization_usage.md) by reading the Amazon CloudWatch metrics the deployment publishes. Without these permissions those endpoints cannot answer; nothing else in the deployment is affected.

??? example "Usage API IAM Policy Statement"
    ```json
    {
      "Sid": "UsageApiMetricRead",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics"
      ],
      "Resource": "*"
    }
    ```

    !!! note "Why the resource is `*`"
        CloudWatch metric actions do not support resource-level permissions: there is no metric ARN to name, so `cloudwatch:GetMetricData` and `cloudwatch:ListMetrics` can only be granted on `*`. The `cloudwatch:namespace` condition key is documented for `PutMetricData` and OTLP ingest, not for reads, so it cannot narrow these two either. See [Actions, resources, and condition keys for Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html).

!!! warning "`cloudwatch:GetMetricData` is billed per metric read"
    It is also **excluded from the CloudWatch free tier**. Price the endpoints before you expose them — [Usage API Query Cost](operations_cost_management.md#usage-api-cost).

---

## :material-account-cash: Per-User Cost Attribution (Optional) { #per-user-cost-attribution }

**Environment Variables**: [`AWS_BEDROCK_USER_ROLE_ARN`](operations_configuration_bedrock.md#aws-bedrock-user-role-arn)

Required to run each end user's model calls under a role session of their own, so AWS reports [their spend separately](operations_cost_management.md#per-user-attribution). Three policies are involved: the server's own role must be allowed to open the sessions, the end user role must trust it to do so, and the end user role must be allowed to invoke models.

**1. On the server's role** — allow it to open sessions of the end user role, and of that role only:

??? example "Server Role IAM Policy Statement"
    ```json
    {
      "Sid": "EndUserRoleSessions",
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Resource": "arn:aws:iam::ACCOUNT_ID:role/stdapi-ai-end-user"
    }
    ```

**2. Trust policy of the end user role** — allow the server's role, and nothing else, to assume it *and* to tag the session. `sts:TagSession` is a separate action: without it, every session that carries the end user tag is denied.

??? example "End User Role Trust Policy"
    ```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::ACCOUNT_ID:role/stdapi-ai-task-role"
          },
          "Action": [
            "sts:AssumeRole",
            "sts:TagSession"
          ]
        }
      ]
    }
    ```

**3. Permission policy of the end user role** — everything AWS authorizes against the caller of a model invocation: the invocation actions on the models the deployment serves, the guardrail the invocation carries, and the S3 objects it references:

??? example "End User Role IAM Policy Statements"
    ```json
    {
      "Sid": "EndUserModelInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*:ACCOUNT_ID:inference-profile/*",
        "arn:aws:bedrock:*:ACCOUNT_ID:application-inference-profile/*",
        "arn:aws:bedrock:*:ACCOUNT_ID:default-prompt-router/*",
        "arn:aws:bedrock:*::foundation-model/*",
        "arn:aws:bedrock:*:ACCOUNT_ID:marketplace/model-endpoint/*"
      ]
    },
    {
      "Sid": "EndUserApplyGuardrail",
      "Effect": "Allow",
      "Action": [
        "bedrock:ApplyGuardrail"
      ],
      "Resource": "arn:aws:bedrock:*:ACCOUNT_ID:guardrail/*"
    },
    {
      "Sid": "EndUserS3ReferencedMedia",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::AWS_S3_BUCKET_VALUE/*"
    }
    ```

    **If the buckets it reads use KMS encryption**, also add:

    ```json
    {
      "Sid": "EndUserS3ReferencedMediaKMS",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "s3.REGION.amazonaws.com"
        }
      }
    }
    ```

Replace `ACCOUNT_ID` with your AWS account ID, `stdapi-ai-task-role` with the role the server runs as, and `AWS_S3_BUCKET_VALUE` with each bucket an invocation can reference by URI (see the S3 warning below).

!!! warning "An inference profile needs the foundation models behind it"
    A cross-region inference profile routes to a foundation model in each of its Regions, and AWS authorizes **both** the profile ARN and every foundation model ARN it reaches. A policy naming only `inference-profile/...` fails with an access-denied error naming `foundation-model/...` in a Region you never configured. Keep `arn:aws:bedrock:*::foundation-model/...` alongside the profile, or the call is denied.

!!! warning "A Marketplace model endpoint is authorized against a different resource shape"
    `bedrock:InvokeModel` on a Marketplace model endpoint is authorized against `arn:aws:bedrock:*:ACCOUNT_ID:marketplace/model-endpoint/*` — **not** against the SageMaker endpoint ARN the request names. A policy that only lists `foundation-model/*` and the inference-profile forms above denies every Marketplace endpoint invocation with an access-denied error, even though the same statement already covers ordinary models. Keep this resource whenever [`AWS_BEDROCK_MARKETPLACE_ENDPOINTS_ENABLED`](operations_configuration_models.md#bedrock-marketplace-endpoints-enabled) or [`AWS_BEDROCK_ALLOW_MARKETPLACE_ENDPOINT_ARN`](operations_configuration_models.md#bedrock-allow-marketplace-endpoint-arn) can put an endpoint in front of a request under this role.

!!! warning "Media referenced by S3 URI is read as the end user"
    An invocation may carry its media as an `s3Location` rather than inline — [large attachments](features.md#attachment-size) the server uploads to a regional bucket, a Files API `file_id`, or an S3 URI the client sent from an [accepted bucket](operations_configuration_storage.md#aws-s3-accepted-buckets) — and Amazon Bedrock then reads that object **with the session that signed the invocation**, not with the server's role: [the assumed role must have the `s3:GetObject` permission to the Amazon S3 URI](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html). Without the `EndUserS3ReferencedMedia` statement, those requests fail with an access-denied error the caller sees as a `403`, while the same request without per-user attribution succeeds. List every bucket a URI can name: [`AWS_S3_BUCKET`](operations_configuration_storage.md#aws-s3-bucket), each [`AWS_S3_REGIONAL_BUCKETS`](operations_configuration_storage.md#aws-s3-regional-buckets) bucket, and each [`AWS_S3_ACCEPTED_BUCKETS`](operations_configuration_storage.md#aws-s3-accepted-buckets) bucket — with the KMS statement for every encrypted one. The role needs no write action: the upload the server performs before the invocation keeps the server's own identity.

!!! warning "A configured guardrail is authorized against the end user"
    A guardrail applied **during** an invocation — [`AWS_BEDROCK_GUARDRAIL_IDENTIFIER`](operations_configuration_bedrock.md#aws-bedrock-guardrail-identifier), a model alias carrying one, or a request-level `moderation` parameter — is evaluated as part of that invocation, so AWS requires `bedrock:ApplyGuardrail` from the identity making the call. Without the `EndUserApplyGuardrail` statement, every model request fails with an access-denied error as soon as per-user attribution is enabled. See [Set up permissions to use Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-permissions.html). Narrow the resource to your guardrail ARN if you prefer.

!!! note "Name every model ARN form the deployment allows"
    The `Resource` list must cover every ARN a request can resolve to. Add `arn:aws:bedrock:*:ACCOUNT_ID:prompt/*` when [`AWS_BEDROCK_ALLOW_PROMPT_ARN`](operations_configuration_bedrock.md#bedrock-allow-prompt-arn) is enabled, and keep the application inference profile, prompt router and marketplace model endpoint entries above whenever [`AWS_BEDROCK_ALLOW_APPLICATION_INFERENCE_PROFILE_ARN`](operations_configuration_bedrock.md#bedrock-allow-application-profile-arn), [`AWS_BEDROCK_ALLOW_PROMPT_ROUTER_ARN`](operations_configuration_bedrock.md#bedrock-allow-prompt-router-arn), [`AWS_BEDROCK_MARKETPLACE_ENDPOINTS_ENABLED`](operations_configuration_models.md#bedrock-marketplace-endpoints-enabled), [`AWS_BEDROCK_ALLOW_MARKETPLACE_ENDPOINT_ARN`](operations_configuration_models.md#bedrock-allow-marketplace-endpoint-arn) or [`AWS_BEDROCK_MODEL_ARN_MAPPING`](operations_configuration_bedrock.md#bedrock-model-arn-mapping) can put one in front of a model. An ARN form the end user role does not name is denied under it while it still works on the server's role.

    Add the [Web Search](#web-search-iam) actions to this role as well if you serve `web_search` requests: AWS evaluates them when the model actually runs a search, which happens inside the invocation the end user signed. A denied search does not fail the request, it degrades the answer.

!!! danger "A session tag is an access boundary only when the identity is verified"
    The end user identity is taken from the authenticated caller only under [Amazon Cognito authentication](operations_authentication_security.md). With an API key, or with no authentication, it is whatever the client declared in the request body (`safety_identifier`, `user`, `metadata.user_id`) — so any caller holding the key can send another user's identifier and obtain that user's session tag.

    Write policies conditioned on `aws:PrincipalTag/<key>` only when [`AUTHENTICATION_MODE`](operations_configuration_authentication.md#authentication-mode) is `cognito`, which is the configuration where every request carries an identity the gateway verified. Anywhere else, treat the tag as cost metadata, never as an authorization input.

!!! tip "Restricting a role per end user"
    Where the identity is verified, the session tag makes it testable in a policy: compare it to something on the resource side, so each session reaches only its own data — `"StringEquals": {"aws:ResourceTag/user": "${aws:PrincipalTag/user}"}`, an `s3:prefix` condition, or a `Resource` ARN embedding `${aws:PrincipalTag/user}`. A condition comparing the tag to itself always matches and restricts nothing. A `Deny` on any tag value the deployment does not expect is the other half of the same pattern. Set [`AWS_BEDROCK_USER_ROLE_TAG_KEY`](operations_configuration_bedrock.md#aws-bedrock-user-role-tag-key) to the key the policy tests.

!!! note "Scope"
    Only Bedrock model invocations run under the end user role, together with the guardrail applied during them and the S3 read Amazon Bedrock performs for an `s3Location` they carry. Standalone guardrail evaluations (the [Moderations API](api_openai_moderations.md)), reranking, video generation and its output files, speech, transcription and translation keep the server's own role, so the end user role needs none of their permissions — and the server's role still needs all of them.

---

## :material-key: API Key Authentication (Optional)

Required if you configure API authentication. See the [Authentication](operations_configuration_authentication.md#authentication) configuration section.

### SSM Parameter Store

**Environment Variables**: [`API_KEY_SSM_PARAMETER`](operations_configuration_authentication.md#api-key-ssm)

??? example "SSM Parameter Store IAM Policy Statements"
    ```json
    {
      "Sid": "SSMParameterAccess",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter"
      ],
      "Resource": "arn:aws:ssm:REGION:ACCOUNT_ID:parameter/API_KEY_SSM_PARAMETER_VALUE"
    }
    ```

    !!! info "Replace Parameter Path"
        Replace `API_KEY_SSM_PARAMETER_VALUE` with the value of your [`API_KEY_SSM_PARAMETER`](operations_configuration_authentication.md#api-key-ssm) environment variable (e.g., `/stdapi/prod/api-key`), and `REGION` with the server's own region (`AWS_REGION`) — parameters are read there, not in the Bedrock regions.

    **If using encrypted SSM parameters**, also add:

    ```json
    {
      "Sid": "KMSDecryptionForSSM",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "ssm.REGION.amazonaws.com"
        }
      }
    }
    ```

    !!! tip "KMS Security"
        The `kms:ViaService` condition restricts KMS key usage to SSM service calls only.

### Secrets Manager

**Environment Variables**: [`API_KEY_SECRETSMANAGER_SECRET`](operations_configuration_authentication.md#api-key-secretsmanager-secret)

??? example "Secrets Manager IAM Policy Statement"
    ```json
    {
      "Sid": "SecretsManagerAccess",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:API_KEY_SECRETSMANAGER_SECRET_VALUE"
    }
    ```

    !!! info "Replace Secret Name"
        Replace `API_KEY_SECRETSMANAGER_SECRET_VALUE` with the value of your [`API_KEY_SECRETSMANAGER_SECRET`](operations_configuration_authentication.md#api-key-secretsmanager-secret) environment variable (e.g., `stdapi-api-key`), and `REGION` with the server's own region (`AWS_REGION`) — secrets are read there, not in the Bedrock regions.

---

## :material-file-document: Complete Policy Examples

??? example "Minimal Policy (Bedrock Only)"
    ```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "BedrockModelInvoke",
          "Effect": "Allow",
          "Action": [
            "bedrock:CountTokens",
            "bedrock:GetAsyncInvoke",
            "bedrock:InvokeGuardrailChecks",
            "bedrock:InvokeModel",
            "bedrock:InvokeModelWithBidirectionalStream",
            "bedrock:InvokeModelWithResponseStream",
            "bedrock:InvokeTool",
            "bedrock:Rerank"
          ],
          "Resource": "*"
        },
        {
          "Sid": "BedrockAsyncInvokeTagging",
          "Effect": "Allow",
          "Action": [
            "bedrock:TagResource"
          ],
          "Resource": "arn:aws:bedrock:*:*:async-invoke/*"
        },
        {
          "Sid": "BedrockModelDiscovery",
          "Effect": "Allow",
          "Action": [
            "bedrock:ListFoundationModels",
            "bedrock:GetFoundationModelAvailability",
            "bedrock:ListProvisionedModelThroughputs",
            "bedrock:ListInferenceProfiles"
          ],
          "Resource": "*"
        },
        {
          "Sid": "BedrockMarketplaceAutoSubscribe",
          "Effect": "Allow",
          "Action": [
            "aws-marketplace:Subscribe",
            "aws-marketplace:ViewSubscriptions"
          ],
          "Resource": "*"
        }
      ]
    }
    ```

    !!! note "Marketplace Auto-Subscribe (Default Enabled)"
        The marketplace permissions are included because `AWS_BEDROCK_MARKETPLACE_AUTO_SUBSCRIBE` defaults to `true`. If you set it to `false`, you can remove the `BedrockMarketplaceAutoSubscribe` statement.

??? example "Production Policy (Bedrock + S3 + Authentication)"
    ```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "BedrockModelInvoke",
          "Effect": "Allow",
          "Action": [
            "bedrock:CountTokens",
            "bedrock:GetAsyncInvoke",
            "bedrock:InvokeGuardrailChecks",
            "bedrock:InvokeModel",
            "bedrock:InvokeModelWithBidirectionalStream",
            "bedrock:InvokeModelWithResponseStream",
            "bedrock:InvokeTool",
            "bedrock:Rerank"
          ],
          "Resource": "*"
        },
        {
          "Sid": "BedrockAsyncInvokeTagging",
          "Effect": "Allow",
          "Action": [
            "bedrock:TagResource"
          ],
          "Resource": "arn:aws:bedrock:*:*:async-invoke/*"
        },
        {
          "Sid": "BedrockModelDiscovery",
          "Effect": "Allow",
          "Action": [
            "bedrock:ListFoundationModels",
            "bedrock:GetFoundationModelAvailability",
            "bedrock:ListProvisionedModelThroughputs",
            "bedrock:ListInferenceProfiles"
          ],
          "Resource": "*"
        },
        {
          "Sid": "BedrockMarketplaceAutoSubscribe",
          "Effect": "Allow",
          "Action": [
            "aws-marketplace:Subscribe",
            "aws-marketplace:ViewSubscriptions"
          ],
          "Resource": "*"
        },
        {
          "Sid": "S3FileStorage",
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:PutObjectTagging",
            "s3:GetObject",
            "s3:DeleteObject",
            "s3:AbortMultipartUpload",
            "s3:ListMultipartUploadParts"
          ],
          "Resource": "arn:aws:s3:::my-stdapi-bucket/*"
        },
        {
          "Sid": "S3FileStorageList",
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket",
            "s3:ListBucketMultipartUploads"
          ],
          "Resource": "arn:aws:s3:::my-stdapi-bucket"
        },
        {
          "Sid": "SSMParameterAccess",
          "Effect": "Allow",
          "Action": [
            "ssm:GetParameter"
          ],
          "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/stdapi/prod/api-key"
        },
        {
          "Sid": "PricingCatalog",
          "Effect": "Allow",
          "Action": [
            "pricing:GetProducts"
          ],
          "Resource": "*"
        },
        {
          "Sid": "UsageApiMetricRead",
          "Effect": "Allow",
          "Action": [
            "cloudwatch:GetMetricData",
            "cloudwatch:ListMetrics"
          ],
          "Resource": "*"
        }
      ]
    }
    ```

    !!! note "Marketplace Auto-Subscribe (Default Enabled)"
        The marketplace permissions are included because `AWS_BEDROCK_MARKETPLACE_AUTO_SUBSCRIBE` defaults to `true`. If you set it to `false`, you can remove the `BedrockMarketplaceAutoSubscribe` statement to follow the principle of least privilege.

    !!! note "Cost Tracking (Opt-In)"
        `PricingCatalog` is only needed when [`COST_TRACKING`](operations_configuration_observability.md#cost-tracking) is set to `true`; remove it otherwise.

    !!! note "Usage API (Opt-In)"
        `UsageApiMetricRead` is only needed when [`USAGE_API`](operations_configuration_observability.md#usage-api) is set to `true`; remove it otherwise. See [Usage API](#usage-api-iam) for why the resource cannot be narrowed, and [Usage API Query Cost](operations_cost_management.md#usage-api-cost) for what the reads are billed at.

---

## :material-account: IAM Role vs. IAM User

stdapi.ai supports both IAM roles and IAM users:

- **:material-aws: IAM Role (Recommended)**: Use when running on EC2, ECS, Lambda, or other AWS compute services. Attach the policy to the instance/task role.
- **:material-account: IAM User**: Use when running outside AWS or for development. Create an IAM user with the required permissions and configure AWS credentials via environment variables or AWS CLI configuration.

!!! success "Best Practice: Use IAM Roles"
    When deploying on AWS infrastructure, always prefer IAM roles over IAM users with access keys. IAM roles provide automatic credential rotation and better security.

---

## :material-tag: AWS Tag Policies

If your AWS organization enforces a [tag policy](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_tag-policies.html), the following tag keys must be allowed on the relevant resource types.

| Tag key | Value | Applied to |
|---------|-------|------------|
| `stdapi-ai.expires` | `"true"` | S3 objects (Files API expiry) |
| `stdapi-ai.request_id` | request UUID | Bedrock async jobs, Transcribe jobs |
| `stdapi-ai.server_id` | server instance name | Bedrock async jobs, Transcribe jobs |
| `stdapi-ai.user_id` | user identifier | Bedrock async jobs, Transcribe jobs (when user identity is known) |

---

## :material-arrow-right: Next Steps

<div class="grid cards" markdown>

- :material-cog: [**Configuration Reference**](operations_configuration.md) — Environment variables for every feature
- :material-lock: [**Authentication & Security**](operations_authentication_security.md) — Secure your deployment
- :material-server-network: [**Advanced Deployment**](operations_deploy_advanced.md) — Terraform infrastructure examples
- :material-help-circle: [**Troubleshooting**](operations_troubleshooting.md) — Diagnose permission errors

</div>
