Arvados™ Docs
  1. Concepts
    1. API Reference
    2. API Authorization
    3. REST API syntax
    4. Common resource methods
    5. Common resource fields
  2. Permission and authentication
    1. users
    2. groups
    3. api_client_authorizations
    4. links
    5. computed_permissions
    6. authorized_keys
    7. credentials
    8. user_agreements
    9. virtual_machines
  3. Data management
    1. WebDAV
    2. S3 API
    3. Keep-web URL patterns
    4. Projects and filter groups
    5. Metadata properties
    6. collections
    7. logs
    8. keep_services
  4. Container engine
    1. container_requests
    2. containers
    3. workflows
    4. cloud dispatcher

credentials

API endpoint base: https://pirca.arvadosapi.com/arvados/v1/credentials

Object type: oss07

Example UUID: zzzzz-oss07-0123456789abcde

Resource

Stores a credential, such as a username/password or API token, for use by running containers to access an external resource on the user’s behalf.

Each Credential offers the following attributes, in addition to the Common resource fields:

Attribute Type Description
name string Name for the credential, unique by owner.
description string Free text description of this credential.
credential_class string The type of credential stored in this record. See below for more information.
scopes array of string (optional) One or more specific resources this credential applies to.
external_id string The non-secret part of the credential.
secret string The secret part of the credential that should kept hidden where possible.
expires_at timestamp Date at which the secret field is not longer valid and can no longer be accessed (and may be scrubbed from the database). If expires_at has past, any attempts to access the secret endpoint (see below) also return an error.

The secret field can be set when the record is created or updated by users with at can_write permission, however the value of secret is not returned in the regular get or list API calls, and cannot be used in queries.

Credentials can be read using an Arvados token issued to a container running on behalf of a user who has can_read permission to the credential, using the secret API call (see below). Calling the secret API with a regular Arvados token (i.e. not associated with a running container) will return a permission denied error.

This design is intended to minimize accidental exposure of the secret material, but does not inherently protect it from users who have been given can_read access, since it is necessary for code running on those user’s behalf to access the secret in order to make use of it.

As of Arvados 3.2, all credentials are owned by the system user and the name field must be unique on a given Arvados instance. Credentials are shared using normal permission links.

Credential classes

The credential_class field is used to identify what kind of credential is stored and how to interpret the other fields of the record.

aws_access_key

Attribute Description
credential_class String “aws_access_key”
scopes (optional, not yet implemented in Arvados 3.2) A list of S3 buckets (in the form “s3://bucketname”) to which these credentials grant access.
external_id The value of “aws_access_key_id” from ~/.aws/credentials
secret The value of “aws_secret_access_key” ~/.aws/credentials

Methods

See Common resource methods for more information about create, delete, get, list, and update.

Required arguments are displayed in green.

create

Create a new Credential.

Arguments:

Argument Type Description Location Example
credential object Credential resource request body

delete

Delete an existing Credential.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Credential in question. path

get

Get a credential by UUID. The secret field is not returned in get API calls. To get the value of secret, use the secret API call.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Credential in question. path

list

List credentials. The secret field is not returned in list API calls, and cannot be used in queries. To get the value of secret, use the secret API call.

See common resource list method.

update

Update attributes of an existing credential. May be used to update the value of secret.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Credential in question. path
credential object query

secret

Get the value of secret. Returns a JSON object in the form {"external_id": "...", "secret": "..."}.

Only permitted when called with a Arvados token issued to a container running on behalf of a user who has can_read permission to the credential. Calling this API with a regular Arvados token (i.e. not associated with a running container) will return a permission denied error.

If expires_at has passed, this endpoint will return an error.

Calls to the secret API endpoint are logged as event_type: secret_access in the audit log table.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Credential in question. path
Previous: authorized_keys Next: user_agreements

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.