Credentials API

Manage cloud provider credentials securely.

Security Notice

• Credentials are encrypted at rest using AES-256-GCM
• Secret values are never returned in API responses
• All credential operations are logged for audit

List Credentials

Get all credentials for the authenticated user.

GET /api/credentials
Authorization: Bearer <access_token>

Response 200 OK:

{
  "data": [
    {
      "id": "uuid",
      "name": "production-aws",
      "provider": "aws",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "uuid",
      "name": "staging-azure",
      "provider": "azure",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Note: Sensitive credential values are never returned.

Create Credential

Store new cloud credentials.

AWS Credentials

POST /api/credentials
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "production-aws",
  "provider": "aws",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }
}

Azure Credentials

POST /api/credentials
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "production-azure",
  "provider": "azure",
  "credentials": {
    "subscriptionId": "uuid",
    "tenantId": "uuid",
    "clientId": "uuid",
    "clientSecret": "secret"
  }
}

GCP Credentials

POST /api/credentials
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "production-gcp",
  "provider": "gcp",
  "credentials": {
    "projectId": "my-project",
    "serviceAccountKey": {
      "type": "service_account",
      "project_id": "my-project",
      "private_key_id": "key-id",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "client_email": "sa@my-project.iam.gserviceaccount.com",
      "client_id": "123456789",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token"
    }
  }
}

Response 201 Created:

{
  "data": {
    "id": "uuid",
    "name": "production-aws",
    "provider": "aws",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

400 Bad Request - Invalid credentials format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid credentials format",
    "details": [
      {
        "field": "credentials.accessKeyId",
        "message": "AWS Access Key ID is required"
      }
    ]
  }
}

409 Conflict - Duplicate name:

{
  "error": {
    "code": "CONFLICT",
    "message": "Credential with this name already exists"
  }
}

Get Credential

Retrieve credential metadata (not secret values).

GET /api/credentials/:id
Authorization: Bearer <access_token>

Response 200 OK:

{
  "data": {
    "id": "uuid",
    "name": "production-aws",
    "provider": "aws",
    "metadata": {
      "region": "us-east-1",
      "accessKeyId": "AKIA...MPLE"
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Note: Only non-sensitive metadata is returned. Secret keys are masked.

Update Credential

Update credential values.

PUT /api/credentials/:id
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "production-aws-updated",
  "credentials": {
    "accessKeyId": "AKIANEWKEY",
    "secretAccessKey": "newSecretAccessKey",
    "region": "us-west-2"
  }
}

Response 200 OK:

{
  "data": {
    "id": "uuid",
    "name": "production-aws-updated",
    "provider": "aws",
    "updatedAt": "2024-01-15T00:00:00Z"
  }
}

Delete Credential

Remove stored credentials.

DELETE /api/credentials/:id
Authorization: Bearer <access_token>

Response 204 No Content

Errors:

400 Bad Request - Credential in use:

{
  "error": {
    "code": "CREDENTIAL_IN_USE",
    "message": "Cannot delete credential that is assigned to environments",
    "details": {
      "environments": ["production-us-east", "staging-us-west"]
    }
  }
}

Validate Credential

Test if credentials are valid with the cloud provider.

POST /api/credentials/:id/validate
Authorization: Bearer <access_token>

Response 200 OK:

{
  "data": {
    "valid": true,
    "identity": {
      "arn": "arn:aws:iam::123456789:user/deploy-user",
      "accountId": "123456789"
    }
  }
}

Response 200 OK (invalid):

{
  "data": {
    "valid": false,
    "error": "The security token included in the request is invalid"
  }
}

Credential Schemas

AWS

Field	Type	Required	Description
accessKeyId	string	Yes	AWS Access Key ID
secretAccessKey	string	Yes	AWS Secret Access Key
region	string	No	Default region
sessionToken	string	No	Temporary session token

Azure

Field	Type	Required	Description
subscriptionId	string	Yes	Azure Subscription ID
tenantId	string	Yes	Azure AD Tenant ID
clientId	string	Yes	Service Principal App ID
clientSecret	string	Yes	Service Principal Secret

GCP

Field	Type	Required	Description
projectId	string	Yes	GCP Project ID
serviceAccountKey	object	Yes	Service Account JSON key

Best Practices

1. Rotate regularly - Update credentials every 90 days
2. Least privilege - Use minimal required permissions
3. Separate credentials - Use different credentials per environment
4. Monitor usage - Enable CloudTrail/Activity logging
5. Don't share - Each user should have their own credentials