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:

• Please see service configured statuses and operational states description.

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:

• Please see service configured statuses and operational states description.

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:

• operational states description.

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.