prowler/docs/api-reference/providers/secrets/create.mdx

---
title: "Create Provider Secret"
api: "POST /api/v1/providers/secrets"
description: "Add credentials/secrets to authenticate with a cloud provider."
---

Configure authentication credentials for a cloud provider. This endpoint stores the necessary secrets (API keys, role ARNs, service account keys) to allow Prowler to scan your cloud infrastructure.

## Use Cases

- **AWS Role Assumption**: Configure IAM role ARN for cross-account access
- **Azure Service Principal**: Store client ID, client secret, and tenant ID
- **GCP Service Account**: Upload service account JSON key
- **Static Credentials**: Store API keys or access keys (not recommended for production)

## Request Body

The request follows the JSON:API specification:

```json
{
  "data": {
    "type": "provider-secrets",
    "attributes": {
      "name": "Production AWS Credentials",
      "secret_type": "role",
      "secret": {
        "role_arn": "arn:aws:iam::123456789012:role/ProwlerRole",
        "external_id": "unique-external-id"
      }
    },
    "relationships": {
      "provider": {
        "data": {
          "type": "providers",
          "id": "provider-uuid"
        }
      }
    }
  }
}
```

### Attributes

- `name` (optional, string, nullable) - Descriptive name for the secret (3-100 characters)
- `secret_type` (required, enum) - Type of secret:
  - `role` - IAM role assumption (AWS)
  - `service_account` - Service account key (GCP)
  - `static` - Static key-value pairs (API keys, credentials)
- `secret` (required, object) - The actual secret data (varies by secret_type)

### Secret Types and Formats

**AWS Role (`role`):**
```json
{
  "secret": {
    "role_arn": "arn:aws:iam::123456789012:role/ProwlerRole",
    "external_id": "your-external-id"
  }
}
```

**GCP Service Account (`service_account`):**
```json
{
  "secret": {
    "service_account_key": "{\"type\":\"service_account\",\"project_id\":\"my-project\",...}"
  }
}
```

**Azure Service Principal (`static`):**
```json
{
  "secret": {
    "client_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
    "client_secret": "your-client-secret",
    "tenant_id": "tenant-uuid"
  }
}
```

**Static Credentials (`static`):**
```json
{
  "secret": {
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}
```

## Example Requests

### AWS Role Assumption
```bash
curl -X POST "https://api.prowler.com/api/v1/providers/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "provider-secrets",
      "attributes": {
        "name": "Production AWS Role",
        "secret_type": "role",
        "secret": {
          "role_arn": "arn:aws:iam::123456789012:role/ProwlerRole",
          "external_id": "prowler-external-id-12345"
        }
      },
      "relationships": {
        "provider": {
          "data": {
            "type": "providers",
            "id": "provider-uuid"
          }
        }
      }
    }
  }'
```

### GCP Service Account
```bash
curl -X POST "https://api.prowler.com/api/v1/providers/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "provider-secrets",
      "attributes": {
        "name": "GCP Service Account",
        "secret_type": "service_account",
        "secret": {
          "service_account_key": "{\"type\":\"service_account\",\"project_id\":\"my-project-123\",\"private_key_id\":\"key-id\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"prowler@my-project.iam.gserviceaccount.com\",\"client_id\":\"123456789\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\"}"
        }
      },
      "relationships": {
        "provider": {
          "data": {
            "type": "providers",
            "id": "provider-uuid"
          }
        }
      }
    }
  }'
```

## Response

### Success Response (201 Created)

Returns the created secret metadata (sensitive data is not returned):

```json
{
  "data": {
    "type": "provider-secrets",
    "id": "secret-uuid",
    "attributes": {
      "name": "Production AWS Role",
      "secret_type": "role",
      "inserted_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "relationships": {
      "provider": {
        "data": {
          "type": "providers",
          "id": "provider-uuid"
        }
      }
    }
  }
}
```

### Response Fields

- `id` (UUID) - Unique identifier for the secret
- `name` (string, nullable) - Descriptive name (3-100 characters)
- `secret_type` (enum) - Type: `role`, `service_account`, or `static`
- `inserted_at` (datetime, read-only) - Creation timestamp
- `updated_at` (datetime, read-only) - Last modification timestamp

### Error Responses

**400 Bad Request** - Invalid secret format
```json
{
  "errors": [
    {
      "status": "400",
      "title": "Invalid Secret Format",
      "detail": "Role ARN format is invalid"
    }
  ]
}
```

**404 Not Found** - Provider does not exist
```json
{
  "errors": [
    {
      "status": "404",
      "title": "Provider Not Found",
      "detail": "Provider with ID 'provider-uuid' not found"
    }
  ]
}
```

**422 Unprocessable Entity** - Validation error
```json
{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "secret_type is required",
      "source": {
        "pointer": "/data/attributes/secret_type"
      }
    }
  ]
}
```

## Next Steps

After creating a secret:

1. **Test Connection**: Verify the credentials work
   ```bash
   curl -X POST "https://api.prowler.com/api/v1/providers/{provider_id}/connection" \
     -H "Authorization: Bearer YOUR_API_KEY"
   ```

2. **Run First Scan**: Execute a security scan
   ```bash
   curl -X POST "https://api.prowler.com/api/v1/scans" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{"data": {"type": "scans", "attributes": {"provider_id": "provider-uuid"}}}'
   ```

<Warning>
**Security Critical:**
- Secrets are encrypted at rest in Prowler's database
- Use role assumption (AWS) or service accounts (GCP) instead of static credentials
- Never log or expose secret values
- Rotate credentials regularly
- Use least-privilege IAM policies
- For AWS, always use an external ID for role assumption
</Warning>

<Note>
The secret data itself is never returned in API responses after creation. Only metadata about the secret is accessible via the API.
</Note>

<Tip>
**AWS Best Practice:** Create a dedicated IAM role with the `SecurityAudit` managed policy and a trust relationship allowing Prowler to assume it. Use an external ID for additional security.
</Tip>