Service_accounts

The ServiceAccount resource

Represents a service account definition.

A service account is a special type of account intended to represent a non-human user that needs to authenticate and be authorized to access data in Scalr APIs.

Key path

Description

type* (string)

Available values: service-accounts

id (string)

attributes.created-at (string)

attributes.description (string)

The service account description.

attributes.email (string)

A read-only field which is generated when a service account is created. Consists of <name>@<account-domain>.scalr.io

attributes.name (string)

The service account name. The service account email will be created using this name.

attributes.status (string)

Available values: Active, Inactive

The service account status. Can be: Active, Inactive.

relationships.account* (object)

The account ID, the service account belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.created-by (object)

The user who created the service account.

relationships.created-by.data.type* (string)

Available values: users

relationships.created-by.data.id* (string)

links.self (string)

List Service Accounts

GET /api/iacp/v3/service-accounts

This endpoint returns a list of IAM service accounts.

Query Parameters
  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • filter[account] (string) – The account filter.

  • filter[service-account] (string) – The service account filter.

  • filter[email] (string) – The service account name filter.

  • include (array) – The comma-separated list of relationship paths. (Available values: account, created-by)

  • sort (array) – The comma-separated list of attributes. (Available values: description, email, name, status)

  • query (string) – Query string

Example Request:

GET /api/iacp/v3/service-accounts HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": [
        {
          "attributes": {
            "created-at": "2021-09-30T19:55:18Z",
            "description": "Test service account",
            "email": "test@my.scalr.io",
            "name": "test",
            "status": "Active"
          },
          "id": "sa-tmhio4ciohlnk3g",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/service-accounts/sa-tmhio4ciohlnk3g"
          },
          "relationships": {
            "account": {
              "data": {
                "id": "acc-svrcncgh453bi8g",
                "type": "accounts"
              }
            },
            "created-by": {
              "data": {
                "id": "user-svrcmmpcrkmit1g",
                "type": "users"
              }
            }
          },
          "type": "service-accounts"
        },
        {
          "attributes": {
            "created-at": "2021-07-23T09:09:20Z",
            "description": "",
            "email": "service-account1@my.scalr.io",
            "name": "service-account1",
            "status": "Active"
          },
          "id": "sa-tj1q8d0h1itdia8",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/service-accounts/sa-tj1q8d0h1itdia8"
          },
          "relationships": {
            "account": {
              "data": {
                "id": "acc-svrcncgh453bi8g",
                "type": "accounts"
              }
            },
            "created-by": {
              "data": {
                "id": "user-svrcmmpcrkmit1g",
                "type": "users"
              }
            }
          },
          "type": "service-accounts"
        }
      ],
      "included": null,
      "links": {
        "first": "https://my.scalr.io/api/iacp/v3/service-accounts?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "last": "https://my.scalr.io/api/iacp/v3/service-accounts?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "next": null,
        "prev": null,
        "self": "https://my.scalr.io/api/iacp/v3/service-accounts?page%5Bnumber%5D=1&page%5Bsize%5D=20"
      },
      "meta": {
        "pagination": {
          "current-page": 1,
          "next-page": null,
          "prev-page": null,
          "total-count": 2,
          "total-pages": 1
        }
      }
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 4XX – Client error.

  • 5XX – Server error.

Create a Service Account

POST /api/iacp/v3/service-accounts

Create a new IAM service account.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, created-by)

Request body:

Key path

Description

data.type* (string)

Available values: service-accounts

data.id (string)

data.attributes.description (string)

The service account description.

data.attributes.name (string)

The service account name. The service account email will be created using this name.

data.attributes.status (string)

Available values: Active, Inactive

The service account status. Can be: Active, Inactive.

data.relationships.account* (object)

The account ID, the service account belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

Example Request:

POST /api/iacp/v3/service-accounts HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "service-accounts",
    "attributes": {
      "description": "Github Actions service account",
      "name": "github-actions",
      "status": "Active"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "acc-svrcncgh453bi8g"
        }
      }
    }
  }
}
Status Codes
  • 201 Created

    Successfully created.

    Example Respone:

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "created-at": "2021-09-22T13:05:40Z",
          "description": "Github Actions service account",
          "email": "github-actions@mainiacp.my.scalr.io",
          "name": "github-actions",
          "status": "Active"
        },
        "id": "sa-tm483ol3ssniov0",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/service-accounts/sa-tm483ol3ssniov0"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          },
          "created-by": {
            "data": {
              "id": "user-svrcmmpcrkmit1g",
              "type": "users"
            }
          }
        },
        "type": "service-accounts"
      },
      "included": null,
      "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform this action or service accounts functionality is not enabled for this account.

  • 404 Not Found – Relationship not found or user unauthorized.

  • 409 Conflict – User quota exceeded.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Delete a Service Account

DELETE /api/iacp/v3/service-accounts/{service_account}

The endpoint deletes IAM service account by ID.

Parameters
  • service_account (string) – The ID of the service account to delete.

Status Codes

Get a Service Account

GET /api/iacp/v3/service-accounts/{service_account}

This endpoint returns an IAM service account by ID.

Parameters
  • service_account (string) – The ID of the service account.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, created-by)

Example Request:

GET /api/iacp/v3/service-accounts/{service_account} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "created-at": "2021-09-30T19:55:18Z",
          "description": "",
          "email": "test@my.scalr.io",
          "name": "test",
          "status": "Active"
        },
        "id": "sa-tmhio4ciohlnk3g",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/service-accounts/sa-tmhio4ciohlnk3g"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          },
          "created-by": {
            "data": {
              "id": "user-svrcmmpcrkmit1g",
              "type": "users"
            }
          }
        },
        "type": "service-accounts"
      },
      "included": null,
      "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Service account not found.

  • 4XX – Client error.

  • 5XX – Server error.

Update a Service Account

PATCH /api/iacp/v3/service-accounts/{service_account}

This endpoint updates IAM service account by ID.

Parameters
  • service_account (string) – The ID of the service account to update.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, created-by)

Request body:

Key path

Description

data.type* (string)

Available values: service-accounts

data.id (string)

data.attributes.description (string)

The service account description.

data.attributes.name (string)

The service account name. The service account email will be created using this name.

data.attributes.status (string)

Available values: Active, Inactive

The service account status. Can be: Active, Inactive.

data.relationships.account* (object)

The account ID, the service account belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

Example Request:

PATCH /api/iacp/v3/service-accounts/{service_account} HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data":{
    "type":"service-accounts",
    "attributes":{
      "description":"Test service account",
      "name":"test",
      "status":"Active"
    },
    "relationships":{}
  }
}
Status Codes
  • 200 OK

    Successfully updated.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "created-at": "2021-09-30T19:55:18Z",
          "description": "Test service account",
          "email": "test@my.scalr.io",
          "name": "test",
          "status": "Active"
        },
        "id": "sa-tmhio4ciohlnk3g",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/service-accounts/sa-tmhio4ciohlnk3g"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          },
          "created-by": {
            "data": {
              "id": "user-svrcmmpcrkmit1g",
              "type": "users"
            }
          }
        },
        "type": "service-accounts"
      },
      "included": null,
      "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Service account not found.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.