Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Version:

Onezone REST API Oneprovider REST API Onepanel REST API

Version:

Create named token for a user

POST /users/{id}/tokens/named

Creates a new named token for specific user. The token name must be unique for the user.

In case of invite tokens, invite / add member privileges are required in the target entity to create a token. For example, space_add_group in the space when creating a groupJoinSpace invite token.

This operation is available for the token owner (subject), otherwise requires oz_tokens_manage admin privilege.

You can learn more about named and temporary tokens here.

Example cURL requests

Create named token for a user

curl -u username:password -X POST -d '{"name": "new-token-1"}' \
-H 'Content-type: application/json' \
https://$HOST/api/v3/onezone/users/$USER_ID/tokens/named

Path parameters

Parameter	Type & Description
id required	string User Id

Request body

application/json

Properties of the new named token.

Property Type & Description

name

string (TokenPropertyName)

Token name (unique for subject user/provider)

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

customMetadata

object (TokenPropertyCustomMetadata)

Arbitrary user metadata (JSON) attached to the token

revoked

boolean (TokenPropertyRevoked)

Determines if this token is revoked (cannot be used) - can be toggled at will

privileges

array of strings

A list of privileges that will be granted to the user that consumes the invite token. NOTE that this parameter is recognized only if the token type is invite token and the invitation target supports member privileges. The privileges must be valid for given invite token type (for example, group privileges for userJoinGroup type).

usageLimit

integer (InviteTokenPropertyUsageLimit)

Usage limit for an invite token (positive integer) or "infinity". NOTE that this parameter is recognized only if the token type is invite token.

Request Examples

application/json

{
  "name": "New Token",
  "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"
      ]
    }
  ],
  "customMetadata": {
    "jobName": "experiment-15",
    "vm": "worker156.cloud.local"
  },
  "revoked": false,
  "privileges": [
    "cluster_view",
    "cluster_update",
    "cluster_delete",
    "cluster_view_privileges",
    "cluster_set_privileges"
  ],
  "usageLimit": 15
}

Responses

application/json

201

Response body contains the Id of newly created named token and its serialized form. Additionally, URI of the created named token in form https://$HOST/api/onezone/v3/tokens/named/{id} is returned in the response Location header.

Property	Type & Description
tokenId string (TokenPropertyId) Unique identifier of the token
token string (SerializedToken) The token in serialized form.

Example

application/json

{
  "tokenId": "2b5d0dd5aa6443a69277b5ce0544fec2",
  "token": "MDAxNWxvY2F0aW9uIG9uZXpvbmUKMDAzYmlkZW50aWZpZXIgOEhmSEFSSGdrbHFCa1pWSTR"
}

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