Skip to content

21. Managed Object Storage

Object Storage is a computer data storage architecture that manages data as objects as opposed to block storage which manages data as blocks within sectors and tracks. Managed Object storage is commonly used to manage large amounts of unstructured data for example storing large datasets like photos, music, or files in online collaboration services. All customers data is encrypted by default using encryption at rest.

Managed Object Storage API commands allow creation, management and deletion of Object Storage devices as well as viewing Object Storage network data usage. Managed Object Storage is fully S3-compliant allowing file and bucket management using existing S3 clients.

API follows JSON Merge Patch semantics. Note when modifying nested structures payload should contain entire array, which in a sense is PUT within PATCH for them. JSON Merge Patch uses null to explicitly indicate property deletion while absent properties are ignored, i.e. not modified.

List regions

Returns a list of available managed object storage regions.

Request

GET /1.3/object-storage-2/regions HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "name": "europe-1",
        "primary_zone": "fi-hel1",
        "zones": [
            {
                "name": "fi-hel1"
            },
            {
                "name": "de-fra1"
            }
        ]
    }
]

Get region details

Returns object storage region details by given {name}.

Request

GET /1.3/object-storage-2/regions/{name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "name": "europe-1",
    "primary_zone": "fi-hel1",
    "zones": [
        {
            "name": "fi-hel1"
        },
        {
            "name": "de-fra1"
        }
    ]
}

Create service

Creates a new object storage service.

Request

POST /1.3/object-storage-2 HTTP/1.1
{
    "name": "example-service",
    "region": "example",
    "configured_status": "started",
    "networks": [
        {
            "name": "example-public-network",
            "type": "public",
            "family": "IPv4"
        },
        {
            "name": "example-private-network",
            "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
            "type": "private",
            "family": "IPv4"
        }
    ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the service must be unique within customer account.
region A valid region identifier, e.g. europe-1 yes Region in which the service will be hosted, see regions.
configured_status started / stopped yes Service status managed by the customer.
networks An array of 0-8 network objects no Attached networks from where object storage can be used. Private networks must reside in object storage region.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List services

Returns a list of object storage services.

Request

GET /1.3/object-storage-2 HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
limit 0-100 10 no Number of entries to receive at most.
offset >= 0 0 no Offset for retrieved results.
sort created_at,-created_at -created_at no Order of returned results.

Normal response

HTTP/1.1 200 OK
[
    {
        "configured_status": "started",
        "created_at": "2023-05-07T15:55:24.655776Z",
        "custom_domains": [
          {
            "domain_name": "objects.example-company.com",
            "type": "public"
          }
        ],
        "endpoints": [
            {
                "domain_name": "7mf5k.upbucket.com",
                "iam_url": "https://7mf5k.upbucket.com:4443/iam",
                "sts_url": "https://7mf5k.upbucket.com:4443/sts",
                "type": "public"
            },
            {
                "domain_name": "7mf5k-private.upbucket.com",
                "iam_url": "https://7mf5k-private.upbucket.com:4443/iam",
                "sts_url": "https://7mf5k-private.upbucket.com:4443/sts",
                "type": "private"
            }
        ],
        "labels": [
          {
            "key": "example-key",
            "value": "example-value"
          }
        ],
        "name": "example-service",
        "networks": [
            {
                "family": "IPv4",
                "name": "example-public-network",
                "type": "public"
            },
            {
                "family": "IPv4",
                "name": "example-private-network",
                "type": "private",
                "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4"
            }
        ],
        "operational_state": "running",
        "region": "europe-1",
        "state_messages": [],
        "updated_at": "2023-05-07T21:38:15.757405Z",
      "usage": {
        "total_objects": 310499,
        "total_size_bytes": 32414921734
      },
        "uuid": "1200ecde-db95-4d1c-9133-6508f3232567"
    }
]

Notes:

Get service details

Returns object storage service details by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "configured_status": "started",
    "created_at": "2023-05-07T15:55:24.655776Z",
    "custom_domains": [],
    "endpoints": [
        {
            "domain_name": "7mf5k.upbucket.com",
            "iam_url": "https://7mf5k.upbucket.com:4443/iam",
            "sts_url": "https://7mf5k.upbucket.com:4443/sts",
            "type": "public"
        },
        {
            "domain_name": "7mf5k-private.upbucket.com",
            "iam_url": "https://7mf5k-private.upbucket.com:4443/iam",
            "sts_url": "https://7mf5k-private.upbucket.com:4443/sts",
            "type": "private"
        }
    ],
    "labels": [
      {
        "key": "example-key",
        "value": "example-value"
      }
    ],
    "name": "example-service",
    "networks": [
        {
            "family": "IPv4",
            "name": "example-public-network",
            "type": "public"
        },
        {
            "family": "IPv4",
            "name": "example-private-network",
            "type": "private",
            "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4"
        }
    ],
    "operational_state": "setup-checkup",
    "region": "europe-1",
    "state_messages": [
      {
        "code": "waiting_certificate_issuing",
        "created_at": "2025-01-16T11:20:40.372611Z",
        "message": "Certificate issuing is in progress for domains: 7mf5k-private.upbucket.com, *.7mf5k-private.upbucket.com.",
        "operational_state": "setup-checkup",
        "updated_at": "2025-01-16T11:20:40.372611Z"
      }
    ],
    "updated_at": "2023-05-07T21:38:15.757405Z",
    "usage": {
      "total_objects": 310499,
      "total_size_bytes": 32414921734
    },
    "users": [
        {
            "access_keys": [
                {
                    "access_key_id": "AKIA63F41D01345BB477",
                    "created_at": "2023-05-07T20:52:19.705405Z",
                    "last_used_at": "2023-05-07T20:52:17Z",
                    "status": "Active"
                }
            ],
            "arn": "urn:ecs:iam::123bbb5c6a4240409e07f7d89fe28891:user/example_user",
            "created_at": "2023-05-07T15:55:24.655776Z",
            "policies": [
              {
                "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
                "name": "ECSS3FullAccess"
              },
              {
                "arn": "urn:ecs:iam:::policy/IAMFullAccess",
                "name": "IAMFullAccess"
              }
            ],
            "username": "example_user"
        }
    ],
    "uuid": "1200ecde-db95-4d1c-9133-6508f3232567"
}

Notes:

Replace service

Replaces existing object storage service by given {service_uuid}.

Request

PUT /1.3/object-storage-2/{service_uuid} HTTP/1.1
{
    "name": "example-service",  
    "configured_status": "started",
    "networks": [
        {
            "name": "example-public-network",
            "type": "public",
            "family": "IPv4"
        },
        {
            "name": "example-private-network",
            "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
            "type": "private",
            "family": "IPv4"
        }
    ],
    "labels": [
        {
            "key": "example-label-key", 
            "value": "example-label-value"
        }
    ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the service must be unique within customer account.
configured_status started / stopped yes Service status managed by the customer.
networks An array of 0-8 network objects no Attached networks from where object storage can be used. Private networks must reside in object storage region.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Service with provided UUID not found.

Modify service

Modifies existing object storage service by given {service_uuid}.

Request

PATCH /1.3/object-storage-2/{service_uuid} HTTP/1.1
{
    "name": "example-service",
    "configured_status": "started",
    "networks": [
        {
            "name": "example-private-network",
            "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
            "type": "private",
            "family": "IPv4"
        }
    ],
    "labels": null
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ no The name of the service must be unique within customer account.
configured_status started / stopped no Service status managed by the customer.
networks An array of 0-8 network objects no Attached networks from where object storage can be used. Private networks must reside in object storage region.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Service with provided UUID not found.

Delete service

Deletes existing object storage service by given {service_uuid}. By default, the deletion of a service is permitted only after all buckets and IAM resource (users, policies) within the service have been successfully deleted.

Request

Query parameters

Attribute Accepted value Default value Required Description
force true / false false no If the parameter provided the deletion process starts even if service is not empty, e.g. contains buckets with objects or IAM entities. Be careful, once deletion process was started the objects cannot be restored.
DELETE /1.3/object-storage-2/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Service with provided UUID not found.

Create bucket

Creates a new service bucket by the given {service_uuid}.

Request

POST /1.3/object-storage-2/{service_uuid}/buckets HTTP/1.1
{
  "name": "my-bucket-1"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-254 characters true Must be unique within the service, and should contain only alphanumeric, .,- and _.

Normal response

HTTP/1.1 201 Created
{
  "name": "my-bucket-1", 
  "total_objects": 0, 
  "total_size_bytes": 0
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete bucket

Deletes an existing bucket by given {service_uuid} and {bucket_name}. This API call will remove all objects from the bucket permanently and cannot be reversed.

Request

DELETE /1.3/object-storage-2/{service_uuid}/buckets/{bucket_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Get service metrics

Returns object storage metrics by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/metrics HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "total_objects": 1287,
    "total_size_bytes": 48277239
}

Attributes

Attribute Description
total_objects Total amount of uploaded objects.
total_size_bytes Total size of uploaded objects in bytes.

List bucket metrics

Request

GET /1.3/object-storage-2/{service_uuid}/buckets HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
limit 0-100 10 no Number of entries to receive at most.
offset >= 0 0 no Offset for retrieved results.

Normal response

HTTP/1.1 200 OK
[
    {
        "name": "example-bucket-1",
        "total_objects": 157,
        "total_size_bytes": 5293771
    },
    {
        "name": "example-bucket-2",
        "total_objects": 12,
        "total_size_bytes": 832226
    }
]

List service metrics series

Returns Object Storage instance metrics series by a given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/metrics/series HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
from RFC 3339 timestamp 24 hours ago no Beginning of the time range for which to return metrics.
to RFC 3339 timestamp Current time no End of the time range for which to return metrics.
interval 1h-24h string 1h no Metrics aggregation interval.
sort start_at,-start_at -start_at no Order of returned results.
limit 0-100 10 no Number of entries to receive at most.
offset >=0 0 no Offset for retrieved results.

Normal response

HTTP/1.1 200 OK
[
    {
        "bytes_created": 530000,
        "bytes_deleted": 244000,
        "bytes_received": 530000,
        "bytes_total": 7502000,
        "bytes_transmitted": 0,
        "end_at": "2023-10-31T12:00:00Z",
        "objects_created": 79,
        "objects_deleted": 40,
        "objects_total": 1237,
        "start_at": "2023-10-31T11:00:00Z"
    },
    {
        "bytes_created": 490000,
        "bytes_deleted": 248000,
        "bytes_received": 490000,
        "bytes_total": 7216000,
        "bytes_transmitted": 0,
        "end_at": "2023-10-31T11:00:00Z",
        "objects_created": 79,
        "objects_deleted": 40,
        "objects_total": 1198,
        "start_at": "2023-10-31T10:00:00Z"
    },
    {
        "bytes_created": 494000,
        "bytes_deleted": 190000,
        "bytes_received": 494000,
        "bytes_total": 6974000,
        "bytes_transmitted": 0,
        "end_at": "2023-10-31T10:00:00Z",
        "objects_created": 82,
        "objects_deleted": 36,
        "objects_total": 1159,
        "start_at": "2023-10-31T09:00:00Z"
    }
]

Attributes

Attribute Description
bytes_total Total size of data stored as of end_at, in bytes.
bytes_created Bytes created within the time interval marked by start_at and end_at.
bytes_deleted Bytes deleted within the time interval marked by start_at and end_at.
bytes_received Bytes received within the time interval marked by start_at and end_at.
bytes_transmitted Bytes transmitted within the time interval marked by start_at and end_at.
objects_total Total number of objects as of end_at.
objects_created Number of objects created within the time interval marked by start_at and end_at.
objects_deleted Number of objects deleted within the time interval marked by start_at and end_at.
start_at The timestamp marking the start of the data aggregation interval, inclusive.
end_at The timestamp marking the end of the data aggregation interval, exclusive.

Create network

Creates a new service network by given {service_uuid}.

Request

POST /1.3/object-storage-2/{service_uuid}/networks HTTP/1.1

public network:

{
    "name": "example-public-network",
    "type": "public",
    "family": "IPv4"
}

or private network:

{
    "name": "example-private-network",
    "uuid": "03bec0ad-85c3-459e-824d-710f8f24f740",
    "type": "private",
    "family": "IPv4"
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the network must be unique within the service.
uuid A valid network uuid yes Private network uuid. For public networks the field should be omitted.
type public / private yes The type of the network.
family IPv4 yes Network family. IPv6 currently not supported.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List networks

Returns a list of available service networks by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/networks HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "family": "IPv4",
        "name": "example-public-network",
        "type": "public"
    },
    {
        "family": "IPv4",
        "name": "example-private-network",
        "type": "private",
        "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4"
    }
]

Get network details

Returns service network details by given {service_uuid} and {network_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/networks/{network_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "family": "IPv4",
    "name": "example-private-network",
    "type": "private",
    "uuid": "03bec0ad-85c3-459e-824d-710f8f24f740"
}

Delete network

Deletes existing network by given {service_uuid} and {network_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/networks/{network_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

List groups

Returns a list of available service groups by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:group/test-group",
    "created_at": "2024-04-15T16:28:45Z",
    "name": "test-group"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get group

Get a single group identified by {service_uuid}, and {group_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/groups/{group_name} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:group/test-data",
  "created_at": "2024-04-15T16:28:45Z",
  "name": "test-data"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create group

Creates an iam group.

Request

POST /1.3/object-storage-2/{service_uuid}/groups HTTP/1.1
{
  "name": "new-group"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 201 Created
{
  "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:group/new-group",
  "created_at": "2024-04-16T13:25:56Z",
  "name": "new-group"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Attach user to group

Attaches an iam user to a group identified by {group_name}, and {username}.

Request

POST /1.3/object-storage-2/{service_uuid}/groups/{group_name}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 Ok

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Remove user from group

Removes an iam user from the group identified by {group_name}, and {username}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 Ok

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete group

Deletes a group identified by {group_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

List group inline policies

Lists the group inline policies by the given {service_uuid}, and {group_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups/{group_name}/inline-policies HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
    "name": "sample-policy"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get group inline policy

Get the group inline policy by the given {service_uuid}, {group_name} and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups/{group_name}/inline-policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
  "name": "sample-policy"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create group inline policy

Creates a group inline policy by the given {service_uuid}, and {group_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/groups/{group_name}/inline-policies HTTP/1.1
{
  "name": "sample-policy",
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Attributes

Attribute Accepted Value Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.
document 1-6144 characters yes A valid policy document, URL-encoded compliant with RFC 3986.

Normal response

HTTP/1.1 201 Created
{
  "name": "sample-policy",
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete group inline policy

Deletes the group inline policy by the given {service_uuid}, {group_name}, and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name}/inline-policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

List Roles

Lists the roles.

Request

GET /1.3/object-storage-2/{service_uuid}/roles HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "arn": "urn:ecs:iam::12e8c7066c0445c284c1381f899bcee7:role/example",
    "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Principal\":{\"AWS\":[\"urn:ecs:iam::12442a2fbc06434889edb631be2d0968:user/user1\"]},\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
    "created_at": "2024-09-19T12:43:24Z",
    "description": "An example role",
    "inline_policies": [
      {
        "name": "InlinePolicy"
      }
    ],
    "max_session_duration": 36000,
    "name": "example",
    "permissions_boundary": "SamplePolicy",
    "policies": [
      {
        "arn": "urn:ecs:iam::12e8c7066c0445c284c1381f899bcee7:policy/SamplePolicy",
        "name": "SamplePolicy"
      }
    ]
  }
]

Get Role

Get a single role identified by {service_uuid}, and {role_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/roles/{role_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "arn": "urn:ecs:iam::12e8c7066c0445c284c1381f899bcee7:role/example",
  "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Principal\":{\"AWS\":[\"urn:ecs:iam::12442a2fbc06434889edb631be2d0968:user/user1\"]},\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
  "created_at": "2024-09-19T12:43:24Z",
  "description": "An example role",
  "inline_policies": [
    {
      "name": "InlinePolicy"
    }
  ],
  "max_session_duration": 36000,
  "name": "example",
  "permissions_boundary": "SamplePolicy",
  "policies": [
    {
      "arn": "urn:ecs:iam::12e8c7066c0445c284c1381f899bcee7:policy/SamplePolicy",
      "name": "SamplePolicy"
    }
  ],
  "tags": [
    {
      "key": "tag1",
      "value": "key1"
    },
    {
      "key": "tag2",
      "value": "key2"
    }
  ]
}

Error response

Http status Accepted Values Default AcceptedValue
404 Not Found RESOURCE_NOT_FOUND Not found.

Create Role

Creates a service IAM role.

Request

POST /1.3/object-storage-2/{service_uuid}/roles HTTP/1.1
{
  "name": "test-role",
  "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Principal\":{\"AWS\":[\"urn:ecs:iam::ns1:user/test-user\"]},\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
  "description": "A test role.",
  "max_session_duration": 3600,
  "permissions_boundary": "test-policy",
  "tags": [
    {
      "key": "department",
      "value": "Finance"
    },
    {
      "key": "school",
      "value": "University of Helsinki"
    }
  ]
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-64 characters true A valid string to represent the name of the IAM role. Please note that _upcloud-internal-role is reserved for internal use and cannot be created.
assume_role_policy_document Max of 131072 characters true A valid string to represent the policy document that grants an entity permission to assume the role.
description 1-1000 characters false A valid string representing the description of the role.
max_session_duration Range: 900-43200 3600 false The maximum session duration (in seconds) for the specified role.
permissions_boundary 1-128 characters false The policy name that is used to set the permissions boundary for the role.
tags A valid JSON document. false The tags to attach to the role (array of tag items), with a maximum of 50 tags.

Normal response

HTTP/1.1 201 Created
{
  "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:role/test-role",
  "assume_role_policy_document": "{\"Version\": \"2012-10-17\",\"Statement\": [{\"Action\": \"sts:AssumeRole\",\"Principal\": {\"AWS\": [\"urn:ecs:iam::ns1:user/Demby\"]},\"Effect\": \"Allow\",\"Resource\": \"*\"}]}",
  "created_at": "2024-05-07T09:18:17Z",
  "description": "A test role.",
  "max_session_duration": 3600,
  "name": "test-role",
  "policies": [],
  "inline_policies": [],
  "permissions_boundary": "test-policy",
  "tags": [
    {
      "key": "department",
      "value": "Finance"
    },
    {
      "key": "school",
      "value": "University of Helsinki"
    }
  ]
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Update Role

Updates a service's IAM role.

Request

PATCH /1.3/object-storage-2/{service_uuid}/roles/{role_name} HTTP/1.1
{
  "name": "test-role",
  "description": "New description",
  "max_session_duration": 3900
}

Attributes

Attribute AcceptedValue Default value Required Description
description 1-1000 characters false A valid string representing the description of the role.
max_session_duration Range: 900-43200 3600 false The maximum session duration (in seconds) for the specified role.

Normal response

HTTP/1.1 200 OK
{
  "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:role/test-role",
  "assume_role_policy_document": "{\"Version\": \"2012-10-17\",\"Statement\": [{\"Action\": \"sts:AssumeRole\",\"Principal\": {\"AWS\": [\"urn:ecs:iam::ns1:user/Demby\"]},\"Effect\": \"Allow\",\"Resource\": \"*\"}]}",
  "created_at": "2024-05-07T09:18:17Z",
  "description": "New Description",
  "max_session_duration": 3900,
  "name": "test-role",
  "permissions_boundary": {
    "permissions_boundary_arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:policy/test-policy",
    "permissions_boundary_type": "Policy"
  },
  "tags": [
    {
      "key": "department",
      "value": "Finance"
    },
    {
      "key": "school",
      "value": "University of Helsinki"
    }
  ]
}

Error response

Http status Accepted Values Default AcceptedValue
404 Not found RESOURCE_NOT_FOUND Not found.

Delete Role

Deletes a service's IAM role.

Request

DELETE /1.3/object-storage-2/{service_uuid}/role/{role_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
404 Not Found RESOURCE_NOT_FOUND Not found.

List Attached Role Policies

Lists all policies attached to a service's IAM role.

Request

GET /1.3/object-storage-2/{service_uuid}/roles/{role_name}/policies HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "policy_name": "test-policy",
    "policy_arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:policy/test-policy"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
404 Not Found RESOURCE_NOT_FOUND Not found.

Attach Policy To Role

Attaches a policy to a service's IAM role.

Request

POST /1.3/object-storage-2/{service_uuid}/roles/{role_name}/policies HTTP/1.1
{
  "name": "test-policy"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM policy.

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Detach Policy From Role

Detaches a policy from a service's IAM role.

Request

DELETE /1.3/object-storage-2/{service_uuid}/roles/{role_name}/policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
404 Not Found RESOURCE_NOT_FOUND Not found.

Create policy

Creates a new service policy by given {service_uuid}.

Request

POST /1.3/object-storage-2/{service_uuid}/policies HTTP/1.1
{
  "name": "example-policy",
  "description": "example-description",
  "document": "%7B%22Version%22%3A%20%222012-10-17%22%2C%20%20%22Statement%22%3A%20%5B%7B%22Action%22%3A%20%5B%22iam%3AGetUser%22%5D%2C%20%22Resource%22%3A%20%22%2A%22%2C%20%22Effect%22%3A%20%22Allow%22%2C%20%22Sid%22%3A%20%22editor%22%7D%5D%7D"
}

Attributes

Attribute Accepted value Required Description
name 1-128 characters, regexp pattern [\\w+=,.@-]+ yes The name of the policy must be unique within the service.
description 1-1000 characters no The policy description.
document 1-6144 characters yes A valid policy document, URL-encoded compliant with RFC 3986.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List policies

Returns a list of available service policies by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/policies HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "arn": "urn:ecs:iam:::policy/ECSDenyAll",
    "attachment_count": 0,
    "created_at": "2024-02-05T11:06:17Z",
    "default_version_id": "v1",
    "description": "Deny all access.",
    "name": "ECSDenyAll",
    "system": true,
    "updated_at": "2024-02-05T11:06:17Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
    "attachment_count": 1,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides full access to all buckets.",
    "name": "ECSS3FullAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/ECSS3ReadOnlyAccess",
    "attachment_count": 0,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides read only access to all buckets.",
    "name": "ECSS3ReadOnlyAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/IAMFullAccess",
    "attachment_count": 1,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides full access to IAM.",
    "name": "IAMFullAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/IAMReadOnlyAccess",
    "attachment_count": 0,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides read only access to IAM.",
    "name": "IAMReadOnlyAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  }
]

Get policy details

Returns service policy details by given {service_uuid} and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
  "attachment_count": 0,
  "created_at": "2024-02-05T11:06:16Z",
  "default_version_id": "v1",
  "description": "Provides full access to all buckets.",
  "document": "%7B%0A++++%22Version%22%3A+%222012-10-17%22%2C%0A++++%22Statement%22%3A+%5B%0A++++++++%7B%0A++++++++++++%22Effect%22%3A+%22Allow%22%2C%0A++++++++++++%22Action%22%3A+%22s3%3A*%22%2C%0A++++++++++++%22Resource%22%3A+%22*%22%0A++++++++%7D%0A++++%5D%0A%7D",
  "name": "ECSS3FullAccess",
  "system": true,
  "updated_at": "2024-02-05T11:06:16Z"
}

Note: The policy document, URL-encoded compliant with RFC 3986.

Delete policy

Deletes existing policy by given {service_uuid} and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/policies/{policy_name} HTTP/1.1

List IAM Group Policies

Lists IAM policies attached to a group, identified by {service_uuid}, and {group_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups/{group_name}/policies HTTP/1.1
{
  "name": "policy-name"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 200 Ok
[
  {
    "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:policy/test-policy",
    "name": "test-policy"
  }
]

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Attach IAM Group Policy

Attaches a policy to a group, identified by {service_uuid}, and {group_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups/{group_name}/policies HTTP/1.1
{
  "name": "policy-name"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Detach IAM Group Policy

Detaches a policy from a group, identified by {service_uuid}, and {group_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name}/policies/{policy_name} HTTP/1.1

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Create policy version

Creates a policy version by the given {service_uuid}, and {policy_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions HTTP/1.1
{
  "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22%2A%22%5D%2C%22Effect%22%3A%22Deny%22%2C%22Resource%22%3A%22%2A%22%7D%5D%7D",
  "is_default": true
}
{
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":[\"*\"],\"Effect\":\"Deny\",\"Resource\":\"*\"}]}",
  "is_default": true
}

Attributes

Attribute AcceptedValue Default value Required Description
document 1-6144 characters true A valid policy document, URL-encoded compliant with RFC 3986.
is_default true / false false false Determines if the newly created policy version will be set as the default.

Normal response

HTTP/1.1 201 Created
{
  "create_date": "2024-03-27T17:24:38.000071+02:00",
  "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22%2A%22%5D%2C%22Effect%22%3A%22Deny%22%2C%22Resource%22%3A%22%2A%22%7D%5D%7D",
  "is_default": true,
  "version_id": "v2"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

List policy versions

Lists policy versions given by {service_uuid}, and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "create_date": "2024-03-25T12:47:40Z",
    "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22*%22%5D%2C%22Resource%22%3A%22*%22%2C%22Effect%22%3A%22Deny%22%7D%5D%7D",
    "is_default": false,
    "version_id": "v4"
  },
  {
    "create_date": "2024-03-25T12:47:38Z",
    "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22*%22%5D%2C%22Resource%22%3A%22*%22%2C%22Effect%22%3A%22Deny%22%7D%5D%7D",
    "is_default": false,
    "version_id": "v3"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get policy version

Get a single policy version by the given {service_uuid}, {policy_name}, and {policy_version}.

Request

POST /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions/{policy_version} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "create_date": "2024-03-27T17:24:38.000071+02:00",
  "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22%2A%22%5D%2C%22Effect%22%3A%22Deny%22%2C%22Resource%22%3A%22%2A%22%7D%5D%7D",
  "is_default": true,
  "version_id": "v2"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete a policy version

Deletes a policy version by the given {service_uuid}, {policy_name}, and {policy_version}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions/{policy_version} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create user

Creates a new service user by given {service_uuid}.

Request

POST /1.3/object-storage-2/{service_uuid}/users HTTP/1.1
{
    "username": "example_user"
}

Response

{
    "access_keys": [],
    "created_at": "2023-05-07T18:19:16.507681Z",
    "policies": [],
    "username": "example_user"
}

Attributes

Attribute Accepted value Required Description
username 1-64 characters, regexp pattern [\\w+=,.@-]+ yes The name of the user to create. Please note that _upcloud-internal-user is reserved for internal use and cannot be created.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List users

Returns a list of available service users by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/users HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "access_keys": [
            {
                "access_key_id": "AKIA63F41D01345BB477",
                "created_at": "2023-05-07T20:52:19.705405Z",
                "last_used_at": "2023-05-07T20:52:17Z",
                "status": "Active"
            }
        ],
        "arn": "urn:ecs:iam::123bbb5c6a4240409e07f7d89fe28891:user/example_user",
        "created_at": "2023-05-07T15:55:24.655776Z",
        "policies": [
            {
                "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
                "name": "ECSS3FullAccess"
            },
            {
                "arn": "urn:ecs:iam:::policy/IAMFullAccess",
                "name": "IAMFullAccess"
            }
        ],
        "username": "example_user"
    }
]

Get user details

Returns service user details by given {service_uuid} and {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "access_keys": [
        {
            "access_key_id": "AKIA63F41D01345BB477",
            "created_at": "2023-05-07T20:52:19.705405Z",
            "last_used_at": "2023-05-07T20:52:17Z",
            "status": "Active"
        }
    ],
    "arn": "urn:ecs:iam::123bbb5c6a4240409e07f7d89fe28891:user/example_user",
    "created_at": "2023-05-07T15:55:24.655776Z",
    "policies": [
        {
            "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
            "name": "ECSS3FullAccess"
        },
        {
            "arn": "urn:ecs:iam:::policy/IAMFullAccess",
            "name": "IAMFullAccess"
        }
    ],
    "username": "example_user"
}

Delete user

Deletes existing user by given {service_uuid} and {username}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Get user tags

Returns a user's tags by the given {service_uuid}, and {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/tags HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "key": "key",
    "value": "val"
  },
  {
    "key": "key2",
    "value": "val2"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Replace user tags

Replaces a user's tags by the given {service_uuid}, and {username}.

Request

PUT /1.3/object-storage-2/{service_uuid}/users/{username}/tags HTTP/1.1
{
    "key": "key",
    "value": "val"
}

Normal response

HTTP/1.1 200 Ok
{
  "key": "key",
  "value": "val"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete user tags

Deletes a user's tag by the given {service_uuid}, {username}, and {tag_key}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/tags/{tag_key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create user permissions boundary

Creates a user's permissions boundary by the given {service_uuid}, and {username}.

Request

PUT /1.3/object-storage-2/{service_uuid}/users/{username}/permissions-boundary HTTP/1.1
{
    "policy_name": "sample-policy"
}

Attributes

Attribute AcceptedValue Default value Required Description
policy_name 1-128 characters true A valid string to represent the name of the IAM policy.

Normal response

HTTP/1.1 200 Ok
{
  "policy_name": "sample-policy"
}

Delete user permissions boundary

Deletes a user's permissions boundary by the given {service_uuid}, and {username}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/permissions-boundary HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

List user inline policies

Lists the user inline policies by the given {service_uuid}, and {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/inline-policies HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
    "name": "ECSS3FullAccess"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get user inline policy

Get the user inline policy by the given {service_uuid}, {username} and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/inline-policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
  "name": "ECSS3FullAccess"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create user inline policy

Creates a user inline policy by the given {service_uuid}, and {username}.

Request

POST /1.3/object-storage-2/{service_uuid}/users/{username}/inline-policies HTTP/1.1
{
  "name": "ECSS3FullAccess",
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Attributes

Attribute Accepted Value Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.
document 1-6144 characters yes A valid policy document, URL-encoded compliant with RFC 3986.

Normal response

HTTP/1.1 201 Created
{
  "name": "ECSS3FullAccess",
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete user inline policy

Deletes the user inline policy by the given {service_uuid}, {username}, and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/inline-policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create access key

Creates a new access key by given {service_uuid} and {username}.

Request

POST /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys HTTP/1.1

Normal response

HTTP/1.1 201 Created
{
    "access_key_id": "AKIA589142A152F5E423",
    "created_at": "2023-05-07T22:58:26.239729Z",
    "last_used_at": "2023-05-07T22:58:26.239729Z",
    "secret_access_key": "xbINHFALkXjFjmxhAYL8mJnODRDX91OM7cCd2+1Y",
    "status": "Active"
}

Note: customer can get secret_access_key only once on access key creation. UpCloud doesn't store customers secret keys.

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List access keys

Returns a list of available access keys by given {service_uuid} or {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "access_key_id": "AKIA63F41D01345BB477",
        "created_at": "2023-05-07T20:52:19.705405Z",
        "last_used_at": "2023-05-07T20:52:17Z",
        "status": "Active"
    }
]

Get access key details

Returns access key details by given {service_uuid} and {username} and {access-key-id}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys/{access-key-id} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "access_key_id": "AKIA63F41D01345BB477",
    "created_at": "2023-05-07T20:52:19.705405Z",
    "last_used_at": "2023-05-07T20:52:17Z",
    "status": "Active"
}

Modify access key details

Modifies access key details by given {service_uuid} and {username} and {access-key-id}.

Request

PATCH /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys/{access-key-id} HTTP/1.1
{
    "status": "Inactive"
}

Attributes

Attribute Accepted value Required Description
status Active/Inactive no Indicates is the key active or inactive.

Normal response

HTTP/1.1 200 OK

Delete access key

Deletes existing access key by given {service_uuid} and {username} and {access-key-id}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys/{access-key-id} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

List attached user policies

Returns a list of attached user policies by given {service_uuid} or {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/policies HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
    "name": "ECSS3FullAccess"
  },
  {
    "arn": "urn:ecs:iam:::policy/IAMFullAccess",
    "name": "IAMFullAccess"
  }
]

Attach user policy

Attach a policy by given {service_uuid} and {username}.

Request

POST /1.3/object-storage-2/{service_uuid}/users/{username}/policies HTTP/1.1
{
  "name": "ECSS3FullAccess"
}

Attributes

Attribute Accepted value Required Description
name Policy name yes A valid policy name.

Normal response

HTTP/1.1 200 Ok

Detach user policy

Detach a policy by given {service_uuid}, {username} and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Create label

Creates a new label by given {service_uuid}.

Labels used for service filtering.

Labels usage examples

Below are some examples of what certain GET requests might look like.

  • exact match: GET /1.3/object-storage-2?label=env%3Dstaging
  • existence: GET /1.3/object-storage-2?label=env
  • multiple: GET /1.3/object-storage-2?label=env&label=foo%3Dbar
POST /1.3/object-storage-2/{service_uuid}/labels HTTP/1.1
{
    "key": "foo",
    "value": "bar"
}

Attributes

Attribute Accepted value Required Description
key 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ yes Represents the label identifier. The key is unique within a service.
value 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z yes Represents the label value.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List labels

Returns a list of available service labels by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/labels HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "key": "env",
        "value": "staging"
    },
    {
        "key": "foo",
        "value": "bar"
    }
]

Get label details

Returns label details by given {service_uuid} and {key}.

Request

GET /1.3/object-storage-2/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "key": "env",
    "value": "staging"  
}

Modify label

Modifies existing label by given {service_uuid} and {key}.

Request

PATCH /1.3/object-storage-2/{service_uuid}/labels/{key} HTTP/1.1
{
    "key": "env",
    "value": "production"
}

Attributes

Attribute Accepted value Required Description
key 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ no Represents the label identifier. The key is unique within a service.
value 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z / null no Represents the label value.

Normal response

HTTP/1.1 200 OK

Delete label

Deletes existing label by given {service_uuid} and {key}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Service configured status

The service configured status indicates the service's current intended status. Managed by the customer.

Status Description
started The service is running.
stopped The service is stopped.

Service operational state

The service operational state indicates the service's current operational, effective state. Managed by the system.

State Description
pending Indicates newly created service or started reconfiguration.
setup-service Configuring service.
setup-network Configuring network.
setup-tls Configuring TLS certificates.
setup-public-endpoint Configuring public endpoint.
setup-private-endpoint Configuring private endpoint.
setup-dns Updating DNS records.
setup-checkup Verifying object storage correctly configured and running.
running Indicates service up and running.
stopped Indicates service is down.
delete-dns Removing DNS records.
delete-private-endpoint Removing public endpoint.
delete-public-endpoint Removing private endpoint.
delete-tls Removing TLS certificates.
delete-network Reconfiguring network.
delete-service Deleting the service.

Attach custom domain

Attaches a new custom domain to the service identified by {service_uuid}.

A maximum of 5 custom domains can be added per service.

DNS records setup

To attach a custom domain, public access to the service must be enabled and DNS records must contain the following CNAME records. Assume the service has public endpoint zzzzz.upcloudobjects.com and custom domain to be attached is objects.example.com, these are the expected records under example.com domain:

Type Host Target
CNAME objects zzzzz.upcloudobjects.com
CNAME *.objects zzzzz.upcloudobjects.com
CNAME _acme-challenge.objects Domain obtained from DNS challenge request e.g. _acme-challenge.xxxxx.upcloudlb.com or such

Request

POST /1.3/object-storage-2/{service_uuid}/custom-domains HTTP/1.1
{
    "domain_name": "objects.example.com",
    "type": "public"
}

Attributes

Attribute Accepted value Required Description
domain_name Must be a subdomain and consist of 3 to 5 parts such as objects.example.com. Cannot be root-level domain e.g. example.com. yes Custom domain to be added.
type At the moment only public is accepted. yes Type of the custom domain.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
400 Bad Request INVALID_REQUEST Validation error.

Get custom domain details

Returns custom domain details by given {service_uuid} and {domain_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/custom-domains/{domain_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "domain_name": "objects.example.com",
    "type": "public"
}

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

List custom domains

Returns a list of custom domains attached to a service by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/custom-domains HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
   {
        "domain_name": "objects.example.com",
        "type": "public"
    },
    {
        "domain_name": "object2.example.com",
        "type": "public"
    }
]

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Delete custom domain

Deletes existing custom domain by given {service_uuid} and {domain_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/custom-domains/{domain_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Modify custom domain

Modifies existing custom domain by given {service_uuid} and {domain_name}.

Request

PATCH /1.3/object-storage-2/{service_uuid}/custom-domains/{domain_name} HTTP/1.1
{
    "domain_name": "objects.example.com",
    "type": "public"
}

Attributes

Attribute Accepted value Required Description
domain_name Must be a subdomain and consist of 3 to 5 parts such as objects.example.com. Cannot be root-level domain e.g. example.com. yes New modified custom domain.
type At the moment only public is accepted. yes Type of the custom domain.

Normal response

HTTP/1.1 200 OK
{
    "domain_name": "objects.example.com",
    "type": "public"
}

Error response

HTTP status Error code Description
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Resource not found.

List Role Inline Policies

Returns a list of role inline policies by the given {service_uuid}, and {role_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/roles/{role_name}/inline-policies HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
    "name": "sample-policy"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get Role Inline Policies

Returns a role's inline policies by the given {service_uuid}, {role_name}, and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/roles/{role_name}/inline-policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}",
  "name": "sample-policy"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create role inline policy

Creates a role inline policy by the given {service_uuid}, and {role_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/roles/{role_name}/inline-policies HTTP/1.1
{
  "name": "sample-policy",
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.
document 1-6144 characters yes A valid policy document, URL-encoded compliant with RFC 3986.

Normal response

HTTP/1.1 201 Created
{
  "name": "sample-policy",
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Delete role inline policy

Delete a role inline policy by the given {service_uuid}, {role_name} and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/roles/{role_name}/inline-policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create role permissions boundary

Creates a role policy's permissions boundary by the given {service_uuid}, and {role_name}.

Request

PUT /1.3/object-storage-2/{service_uuid}/roles/{role_name}/permissions-boundary HTTP/1.1
{
    "policy_name": "sample-policy"
}

Attributes

Attribute AcceptedValue Default value Required Description
policy_name 1-128 characters true A valid string to represent the name of the IAM policy.

Normal response

HTTP/1.1 200 Ok
{
  "policy_name": "sample-policy"
}

Delete role permissions boundary

Deletes a role permissions boundary by the given {service_uuid}, and {role_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/roles/{role_name}/permissions-boundary HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get role tags

Returns a role's tags by the given {service_uuid}, and {role_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/roles/{role_name}/tags HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "key": "key",
    "value": "val"
  },
  {
    "key": "key2",
    "value": "val2"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Replace role tags

Replaces a role's tags by the given {service_uuid}, and {role_name}.

Request

PUT /1.3/object-storage-2/{service_uuid}/roles/{role_name}/tags HTTP/1.1
{
    "key": "key",
    "value": "val"
}

Normal response

HTTP/1.1 200 Ok
{
  "key": "key",
  "value": "val"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete role tags

Deletes a role's tag by the given {service_uuid}, {role_name}, and {tag_key}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/roles/{role_name}/tags/{tag_key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Assume Role Policy

Assume a role policy by the given {service_uuid}, and {role_name}.

Request

PUT /1.3/object-storage-2/{service_uuid}/roles/{role_name}/assume-role-policy HTTP/1.1
{
  "document":"{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Principal\":{\"AWS\":[\"{{iamuser}}\"]},\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Normal response

HTTP/1.1 200 Ok
{
  "document":"{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sts:AssumeRole\",\"Principal\":{\"AWS\":[\"{{iamuser}}\"]},\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

List jobs

Returns a list of jobs. Jobs are used to sync S3-compatible object storages with UpCloud managed object storages.

Request

GET /1.3/object-storage-2/jobs HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "created_at": "2024-08-27T13:05:26.382642Z",
    "input": {
      "source": {
        "access_key_id": "source-access-key-id",
        "bucket": "source-bucket",
        "endpoint_url": "https://example.source.com"
      },
      "target": {
        "access_key_id": "target-access-key-id",
        "bucket": "target-bucket",
        "endpoint_url": "https://example.target.com"
      },
      "type": "copy"
    },
    "operational_state": "running",
    "output": {
      "bytes": 209715200,
      "error": "",
      "total_bytes": 209715200,
      "transfer_time": "2.278435087"
    },
    "updated_at": "2024-08-27T13:06:46.386309Z",
    "uuid": "12f73f4d-e6ed-4ac0-b9b5-2b40ca3b2de2"
  }
]

Notes:

Get job details

Returns object storage job details by given {uuid}.

Request

GET /1.3/object-storage-2/jobs/{job-uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "created_at": "2024-08-27T13:05:26.382642Z",
  "input": {
    "source": {
      "access_key_id": "source-access-key-id",
      "bucket": "source-bucket",
      "endpoint_url": "https://example.source.com"
    },
    "target": {
      "access_key_id": "target-access-key-id",
      "bucket": "example-target-bucket",
      "endpoint_url": "https://example.target.com"
    },
    "type": "copy"
  },
  "operational_state": "running",
  "output": {
    "bytes": 209715200,
    "error": "",
    "total_bytes": 209715200,
    "transfer_time": "2.278435087"
  },
  "updated_at": "2024-08-27T13:06:46.386309Z",
  "uuid": "12f73f4d-e6ed-4ac0-b9b5-2b40ca3b2de2"
}

Create job

Creates a new job.

Request

POST /1.3/object-storage-2/jobs HTTP/1.1
{
  "type": "copy",
  "source": {
    "access_key_id": "source-access-key-id",
    "secret_access_key": "source-secret-key",
    "endpoint_url": "https://example.source.com",
    "bucket": "source-bucket"
  },
  "target": {
    "access_key_id": "target-access-key-id",
    "secret_access_key": "target-secret-key",
    "endpoint_url": "https://example.target.com",
    "bucket": "target-bucket"
  }
}

Attributes

Attribute Accepted value Required Description
type copy yes The type of the job.
source Source object yes Embedded Job Source.
target Target object yes Embedded Job Target.

Source Attributes

Attribute Accepted value Required Default Description
access_key_id 1-128 characters yes Source storage access key id.
secret_access_key 1-128 characters yes Source storage secret key.
endpoint_url 1-255 characters yes Source endpoint URL can belong to any s3 compatible object storage.
bucket 1-255 characters no The job will be created for particular bucket if provided. If the field is empty or missing, then the job will be created for entire object storage.

Target Attributes

Attribute Accepted value Required Default Description
access_key_id 1-128 characters yes Target storage access key id.
secret_access_key 1-128 characters yes Target storage secret key.
endpoint_url 1-255 characters yes Target endpoint URL must be UpCloud managed object storage URL.
bucket 1-255 characters no The job will be created for particular bucket if provided. If the field is empty or missing, then the job will be created for entire object storage.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

Cancel job

Cancels ongoing job by given {job-uuid}.

Request

POST /1.3/object-storage-2/jobs/{job-uuid}/cancel HTTP/1.1

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.
400 Bad Request INVALID_REQUEST Validation error.

Job operational state

The job operational state indicates the job's current operational, effective state. Managed by the system.

State Description
pending Indicates newly created job.
configuring The job enqueued for configuration.
running Indicates the job is running.
completed The job successfully completed.
failed The job failed.
canceled The job canceled by the user.

State Messages Codes

Code Description
waiting_certificate_issuing Indicates that TLS ceritificate issuing for the service endpoints is in progress. The process is pretty fast, but in some cases it could take up to 10 minutes.
failed_domain_verification Indicates failed domain verification for TLS certificate. In case of custom domains please double check your DNS configuration, see attaching custom domain.