Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Version:

Onezone REST API Oneprovider REST API Onepanel REST API

Version:

Confine a token

POST /tokens/confine

Confines (restricts) a token provided in serialized form with given caveats. Returns the confined token. Does not verify the token.

This operation has public access.

Example cURL requests

Confine a token

curl -d '{
  "token": "MDAxNmxvY2F00aW9uIHJlZ2lzdHJ5CjAwM2JpZGVudGlmaW",
  "caveats": [{"type": "time", "validUntil": 1571147494}]
}' \
-H 'Content-type: application/json' \
https://$HOST/api/v3/onezone/tokens/confine

Request body

application/json

The token to be confined and caveats.

Property Type & Description

token required

string (SerializedToken)

The token in serialized form.

caveats required

array of objects (Caveat)

A list of caveats that confine the token.

type required discriminator string Time caveat - limits the token's validity in time. You can learn more about token caveats here. IP caveat - limits the allowed client IPs to a certain whitelist (masks are supported). You can learn more about token caveats here. ASN caveat - limits the ASNs (Autonomous System Number) from which the token can be utilized. The client's ASN is resolved based on client's IP and MaxMind's GeoLite database. You can learn more about token caveats here. GEO Country caveat - limits the countries from which the token can be utilized. The client's country is resolved based on client's IP and MaxMind's GeoLite database. You can learn more about token caveats here. GEO Region caveat - limits the geographical regions from which the token can be utilized. The available values are the 7 continents (Oceania covers Australia and the pacific islands) or the EU meta region, which matches member countries of the European Union. The client's region is resolved based on client's IP and MaxMind's GeoLite database. You can learn more about token caveats here. Service caveat - limits the services that can process the token. Service is the Onedata service that received the client's request - e.g. the Oneprovider service chosen by a user to mount a Oneclient or make a CDMI request. If the caveat is present, the service must prove its identity by sending their identity token in the `x-onedata-service-token header` along with the request. The services must be encoded using proper service format. You can learn more about token caveats here. Consumer caveat - limits the consumers that can use the token. Consumer is the token bearer that utilizes the token - performs a request with an access token or attempts to consume an invite token. If the caveat is present, the consumer must prove their identity by sending their identity token in the `x-onedata-consumer-token header` along with the request. The consumers must be encoded using proper consumer format. You can learn more about token caveats here. Interface caveat - limits the available interfaces on which the token can be used to a certain one. If the oneclient interface is specified, this caveat is treated as a data access caveat - if added to a token, it greatly limits its power in the system APIs, to the minimum required for data access - see more. You can learn more about token caveats here. API caveat - limits the API operations that can be performed with the token. The operations are whitelisted using the Onedata API matchspec format, which includes the service identifier, operation type (CRUD) and resource identifier. You can learn more about token caveats here. Data readonly caveat - allows only read access to user files. This is a data access caveat - if added to a token, it greatly limits its power in the system APIs, to the minimum required for data access - see more. You can learn more about token caveats here. Example: `{ "type": "data.readonly" }` Data path caveat - limits the paths in which data can be accessed with the token. The paths must be canonical - starting with a slash + space id and without a trailing slash - and must be base64 encoded. If a directory path is given, the token allows to access all nested files and directories starting from the specified directory. This is a data access caveat - if added to a token, it greatly limits its power in the system APIs, to the minimum required for data access - see more. You can learn more about token caveats here. Data objectid caveat - limits the object ids in which data can be accessed with the token. The object ids comply with the CDMI format and can be used in the Oneprovider's REST and CDMI APIs. If a directory object id is given, the token allows to access all nested files and directories starting from the specified directory. This is a data access caveat - if added to a token, it greatly limits its power in the system APIs, to the minimum required for data access - see more. You can learn more about token caveats here.
validUntil required integer Timestamp in seconds (UNIX epoch) when the token expires. Example: `{ "type": "time", "validUntil": 1571147494 }`
whitelist required array of strings List of IPs or masks that are allowed to utilize the token. Example: `{ "type": "ip", "whitelist": [ "189.34.15.0/24", "127.0.0.0/8", "167.73.12.17" ] }`
whitelist required array of integers List of ASNs from which the token can be utilized. Example: `{ "type": "asn", "whitelist": [ 631, 632, 1671 ] }`
filter required string Filter type to be applied: whitelist limits allowed countries to the ones on the list only blacklist limits allowed countries to any region that is not on the list Enum: whitelistblacklist
list required array of strings List of countries (ISO3166 2 letter codes) from which the token can be utilized. Example: `{ "type": "geo.country", "filter": "whitelist", "list": [ "PL", "UK", "DE", "NL" ] }`
filter required string Filter type to be applied: whitelist limits allowed regions to the ones on the list only blacklist limits allowed regions to any region that is not on the list Enum: whitelistblacklist
list required array of strings List of regions from which the token can be utilized. Example: `{ "type": "geo.region", "filter": "blacklist", "list": [ "Asia", "NorthAmerica", "Oceania" ] }`
whitelist required array of strings List of services that are allowed to utilize the token. Example: `{ "type": "service", "whitelist": [ "ozw-onezone", "ozp-onezone", "opp-*", "opw-01c4455bef059353c9dfb35ba93a24f3" ] }`
whitelist required array of strings List of consumers that are allowed to utilize the token. Example: `{ "type": "consumer", "whitelist": [ "usr-d4f5876dbe7f1e7e8a511de6dd31144c", "grp-0921135ee61fe53a3df449365228e9b4", "prv-*" ] }`
interface required string The interface on which this token will be exclusively accepted. Example: `{ "type": "interface", "interface": "rest" }` Enum: restoneclientgraphsync
whitelist required array of strings List of API matchspecs that narrow down allowed API calls. Example: `{ "type": "api", "whitelist": [ "ozw/all/user..:", "all/get/space..:" ] }`
whitelist required array of strings List of base64 encoded file paths in which data can be accessed using the token. Example: `{ "type": "data.path", "whitelist": [ "L2QxYjM4OGY3Yzc=", # /d1b388f7c7 "L2QxYjM4OGY3YzcvZGlyL2ZpbGUudHh0" # /d1b388f7c7/dir/file.txt ] }`
whitelist required array of strings List of CDMI ObjectIds in which data can be accessed using the token. Example: `{ "type": "data.objectid", "whitelist": [ "000000000055D4E4836803640004677569646D000000167", "39592D594E736C676D0000002B43592D347247454C535F6" ] }`

Request Examples

Shell

echo '{"token": "MDAx...", "caveats": [{"type": "time", "validUntil": 1571147494}]}' | onezone-rest-cli confineToken -

Responses

application/json

200

Returns the confined token.

Property	Type & Description
token string (SerializedToken) The token in serialized form.

400

Invalid request.

Property

Type & Description

error

object

Object describing an error.

id required string String identifying the error type. Does not change between error instances.
description required string Human readable error description. May contain information specific to given error instance.
details object Details about the error instance. The object schema is specific to each error type.

Example

application/json

{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}

401

Authentication error.

Property

Type & Description

error

object

Object describing an error.

id required string String identifying the error type. Does not change between error instances.
description required string Human readable error description. May contain information specific to given error instance.
details object Details about the error instance. The object schema is specific to each error type.

Example

application/json

{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}

403

Authorization error.

Property

Type & Description

error

object

Object describing an error.

id required string String identifying the error type. Does not change between error instances.
description required string Human readable error description. May contain information specific to given error instance.
details object Details about the error instance. The object schema is specific to each error type.

Example

application/json

{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}

404

Resource not found.

Property

Type & Description

error

object

Object describing an error.

id required string String identifying the error type. Does not change between error instances.
description required string Human readable error description. May contain information specific to given error instance.
details object Details about the error instance. The object schema is specific to each error type.

Example

application/json

{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}

500

Internal server Error.

Property

Type & Description

error

object

Object describing an error.

id required string String identifying the error type. Does not change between error instances.
description required string Human readable error description. May contain information specific to given error instance.
details object Details about the error instance. The object schema is specific to each error type.

Example

application/json

{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}