Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Create named token for current user

POST /user/tokens/named

Creates a new named token for the 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 can be invoked on behalf of the current user only.

You can learn more about named and temporary tokens here.

Example cURL requests

Create named token for current user

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

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).

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.

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://$ZONE_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."
  }
}