Skip to main content

Secrets reference

The EdgeSecrets class is designed to facilitate secure storage and retrieval of secrets for both users and organizations.

Secrets are JSON-serializable dictionary data values that are managed by Edge and securely stored using Vault. There are two types of secrets: User secrets and Organization secrets.

User secrets are private and only accessible to a user. No other users, including organization administrators, are allowed to access User secrets.

Organization secrets are maintained by organization administrators. They are readable by any user in the organization, but they are only writable by the organization administrator.

# Create a secret
>>> edge.secrets.create_user_secret('my-secret', {'secret': 'value'})
>>> print(edge.secrets.list_user_secrets())
['my-secret']
>>> print(edge.secrets.read_user_secret('my-secret'))
{'secret': 'value'}
note

Jupyter Notebooks in the Analysis app cache plaintext values. When working with the Secrets API, reading secrets directly to a variable is generally safe. However, writing secrets in plain text in your notebook could potentially expose the secret. If you are able to see the secret value in the Jupyter Notebook, then it is being handled insecurely.

Constructor​

Constructing these yourself is not recommended. You should make an EdgeSession and access the .secrets property, which will return an EdgeSecrets object.

Methods​

list_user_secrets​

list_user_secrets -> list(str)

List secrets that belong to a user

Returns​

list(str) Secret names.

read_user_secret​

read_user_secret(secret_name) -> dict

Retrieve a user's stored secret.

Parameters​

  • secret_name (str)
    The name of the secret.

Returns​

dict Dictionary object that is the secret value.

Raises​

  • NotFound: If the secret does not exist.

create_user_secret​

create_user_secret(secret_name, secret)

Creates a user secret

Parameters​

  • secret_name (str)
    The name of the secret. Secret names are alphanumeric, and can include the - (dash) and _ (underscore) characters.

  • secret (dict) The secret value to store. The value must be a Python dictionary that is JSON encodable.

Raises​

  • AlreadyExists: Raised if a secret with the given name already exists.
  • BadEntry: Raised if the secret name is invalid.

update_user_secret​

update_user_secret(secret_name, secret)

Changes a user secret's value.

Parameters​

  • secret_name (str)
    The name of the secret. Secret names are alphanumeric, and can include the - (dash) and _ (underscore) characters.

  • secret (dict) The secret value to store. The value must be a Python dictionary that is JSON encodable.

Raises​

  • NotFound: Raised if a secret with the given name does not exist.
  • BadEntry: Raised if the secret name is invalid.

delete_user_secret​

delete_user_secret(secret_name)

Delete a user secret.

Parameters​

  • secret_name (str)
    The name of the secret to delete.

wrap_user_secret​

wrap_user_secret(secret_name)

Wraps an existing user secret with a single-use wrapping token.

This token can be exchanged directly with Vault via an HTTP POST request, with the X-Vault-Token header value set to the wrapped token. For more information, consult the Vault Documentation.

Parameters​

  • secret_name (str)
    The name of the secret.

Returns​

EdgeWrappedSecret An object with two properties.

  • The token property is the single use wrapping token.
  • The unwrap_url is the URL that can be sent a POST to redeem the token.

Raises​

  • NotFound: Raised if a secret with the given name does not exist.
  • BadEntry: Raised if the secret name is invalid.

list_org_secrets​

list_org_secrets -> list(str)

List secrets for the current organization.

Any user with access to the organization may list an organization's secrets.

Returns​

list(str) Secret names.

read_org_secret​

read_org_secret(secret_name) -> dict

Retrieve an organization's stored secret.

Any user with access to the organization may read an organization's secrets.

Parameters​

  • secret_name (str)
    The name of the secret.

Returns​

The dict object that is the secret value.

Raises​

  • NotFound: If the secret does not exist.

create_org_secret​

create_org_secret(secret_name, secret)

Creates an organization secret.

Only organization administrators may create organization secrets.

Parameters​

  • secret_name (str)
    The name of the secret. Secret names are alphanumeric, and can include the - (dash) and _ (underscore) characters.

  • secret (dict) The secret value to store. The value must be a Python dictionary that is JSON encodable.

Raises​

  • AlreadyExists: Raised if a secret with the given name already exists.
  • BadEntry: Raised if the secret name is invalid.

update_org_secret​

update_org_secret(secret_name, secret)

Changes an organization secret's value.

Only organization administrators may update organization secrets.

Parameters​

  • secret_name (str)
    The name of the secret. Secret names are alphanumeric, and can include the - (dash) and _ (underscore) characters.

  • secret (dict) The secret value to store. The value must be a Python dictionary that is JSON encodable.

Raises​

  • NotFound: Raised if a secret with the given name does not exist.
  • BadEntry: Raised if the secret name is invalid.

delete_org_secret​

delete_org_secret(secret_name)

Delete an organization secret.

Only organization administrators may delete organization secrets.

Parameters​

  • secret_name (str)
    The name of the secret to delete.

wrap_org_secret​

wrap_org_secret(secret_name)

Wraps an existing organization secret with a single-use wrapping token.

This token can be exchanged directly with Vault via an HTTP POST request, with the X-Vault-Token header value set to the wrapped token. For more information, consult the Vault Documentation.

Parameters​

  • secret_name (str)
    The name of the secret.

Returns​

EdgeWrappedSecret An object with two properties.

  • The token property is the single use wrapping token.
  • The unwrap_url is the URL that can be sent a POST to redeem the token.

Raises​

  • NotFound: Raised if a secret with the given name does not exist.
  • BadEntry: Raised if the secret name is invalid.