Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Version:

Onezone REST API Oneprovider REST API Onepanel REST API

Version:

Examine a token

POST /tokens/examine

Examines a token provided in serialized form. Returns all the information that can be inferred from the token. Does not verify the token.

This operation has public access.

Example cURL requests

Examine a token

curl -d '{"token": "MDAxNmxvY2F00aW9uIHJlZ2lzdHJ5CjAwM2JpZGVudGlmaW"}' \
-H 'Content-type: application/json' \
https://$HOST/api/v3/onezone/tokens/examine

Request body

application/json

The token to be examined (encapsulated in an object).

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

Request Examples

Shell

onezone-rest-cli examineToken token==MDAxNmxvY2F00aW9uRVM2TVo5UlZ5cGFjZV9jcm

Responses

application/json

200

Returns the inferred information about the token.

Property Type & Description

onezoneDomain

string (TokenPropertyOnezoneDomain)

Domain of the Onezone service that issued the token.

string (TokenPropertyId)

Unique identifier of the token

persistence

string (TokenPropertyPersistence)

Determines if the token is persistent (named) or not (temporary).

Enum:

namedtemporary

subject

object (TokenPropertySubject)

The subject of the token - the user or Oneprovider in whose name the token was issued. The bearer (consumer) of the token adopts the subject's identity when accessing services with that token.

type string Type of the subject Enum: useroneprovider
id string Id of the subject

type

object (TokenPropertyTokenType)

The type of the token (object)

Enum:

{accessToken: {}}{identityToken: {}}{inviteToken: {"...": "..."}}

accessToken

object

Indicates the access token type - currently has no parameters (empty object)

identityToken

object

Indicates the identity token type - currently has no parameters (empty object)

inviteToken

object (InviteToken)

Indicates the invite token type.

inviteType required

discriminator string

Invite token type - invitation for a user to join a group.

Invite token type - invitation for a group to join a group.

Invite token type - invitation for a user to join a space.

Invite token type - invitation for a group to join a space.

Invite token type - invitation for a provider to support a space.

Invite token type - invitation for a harvester to join a space (become a sink for metadata).

Invite token type - invitation for a user to register a new Oneprovider.

Invite token type - invitation for a user to join a cluster.

Invite token type - invitation for a group to join a cluster.

Invite token type - invitation for a user to join a harvester.

Invite token type - invitation for a group to join a harvester.

Invite token type - invitation for a space to join a harvester (become a source of metadata).

groupId required

string

Id of the invitation target group

groupId required

string

Id of the invitation target group

spaceId required

string

Id of the invitation target space

spaceId required

string

Id of the invitation target space

spaceId required

string

Id of the space to be supported

parameters

object (SupportParameters)

Space support parameters - optional, default to dataWrite = global and metadataReplication = eager.

dataWrite required

string

[NOT YET IMPLEMENTED - always global] indicates if the Oneprovider that supports the space by consuming this token will be able to modify files in the space (global) or not (none).

Enum:

globalnone

metadataReplication required

string

[NOT YET IMPLEMENTED - always eager] indicates the level of metadata replication on the Oneprovider that supports the space by consuming this token. eager - all metadata is replicated, might take days to become in sync if the space is already populated with large amount of data. lazy - only required metadata is replicated when specific file is accessed. none - all metadata is fetched from remote Oneproviders every time a request is performed, which is the slowest option but requires minimal resources on the Oneprovider.

Enum:

eagerlazynone

spaceId required

string

Id of the invitation target space

adminUserId required

string

Id of the user to become an admin of the newly registered Oneprovider

clusterId required

string

Id of the invitation target cluster

clusterId required

string

Id of the invitation target cluster

harvesterId required

string

Id of the invitation target harvester

harvesterId required

string

Id of the invitation target harvester

harvesterId required

string

Id of the invitation target harvester

caveats

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) 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" ] }`

Example

application/json

{
  "onezoneDomain": "onezone.example.com",
  "id": "2b5d0dd5aa6443a69277b5ce0544fec2",
  "persistence": "named",
  "subject": {
    "type": "user",
    "id": "1b510f18b3b05611871c0acdffa9aed4"
  },
  "type": {
    "inviteToken": {
      "inviteType": "userJoinCluster",
      "clusterId": "fb73f7ceff5abd995357abbe01c812ce"
    }
  },
  "caveats": [
    {
      "type": "time",
      "validUntil": 1571147494
    },
    {
      "type": "ip",
      "whitelist": [
        "189.34.15.0/8",
        "127.0.0.0/24",
        "167.73.12.17"
      ]
    }
  ]
}

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."
  }
}