Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Get named token of a user by name

GET /users/{id}/tokens/named/name/{name}

Returns the information about a specific user's named token by token name.

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

Get named token of a user by name

curl -u username:password -X GET \
https://$ZONE_HOST/api/v3/onezone/users/$USER_ID/tokens/named/name/my-token-1
{
  "id": "2b5d0dd5aa6443a69277b5ce0544fec2",
  "name": "my-token-1",
  "subject": {
    "type": "user",
    "id": "c26bab23d12f7389c3c311caf9c15902"
  },
  "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"
      ]
    }
  ],
  "metadata": {
    "creationTime": 1564721024,
    "usageLimit": 15,
    "usageCount": 3,
    "privileges": [
      "space_view",
      "space_read_data",
      "space_view_views",
      "space_view_statistics"
    ],
    "custom": {
      "jobName": "experiment-15",
      "vm": "worker156.cloud.local"
    }
  },
  "revoked": false,
  "token": "MDAxNWxvY2F0aW9uIG9uZXpvbmUKMDAzYmlkZW50aWZpZXIgOEhmSEFSSGdrbHFCa1pWSTR"
}

Path parameters

Parameter Type & Description
id required
string

User Id
name required
string

Token name

Request Examples

Shell
onezone-rest-cli getNamedTokenOfUserByName id=$USER_ID name==my-token-1

Responses

application/json
200

Returns the details of a specific named token.

Property
Type & Description
id
string (TokenPropertyId)

Unique identifier of the token

name
string (TokenPropertyName)

Token name (unique for subject user/provider)

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:
user oneprovider
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).

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.

metadata
object (TokenPropertyMetadata)

Metadata describing the token
creationTime
integer (Timestamp)

Timestamp in seconds (UNIX epoch), e.g. 1563819329.

usageLimit
any

(Invite tokens only) limits how many times the token can be consumed - can be a positive integer or the literal string "infinity"

usageCount
integer

(Invite tokens only) informs how many times the token has been consumed so far

privileges
array of strings

(Invite tokens only) the list of privileges that will be granted to the joining user/group upon token consumption

custom
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

token
string (SerializedToken)

The token in serialized form.

Example

application/json
{
  "id": "2b5d0dd5aa6443a69277b5ce0544fec2",
  "name": "my-token-1",
  "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"
      ]
    }
  ],
  "metadata": {
    "creationTime": 1564721024,
    "usageLimit": 15,
    "usageCount": 3,
    "privileges": [
      "space_view",
      "space_read_data",
      "space_view_views",
      "space_view_statistics"
    ],
    "custom": {
      "jobName": "experiment-15",
      "vm": "worker156.cloud.local"
    }
  },
  "revoked": false,
  "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."
  }
}