Step 1: Authentication

datalad-osf needs to communicate with the OSF to create and modify projects under an associated user account. To enable this, the associated user needs to be authenticated using the osf-credentials command. Therefore, as the very first step, datalad osf-credentials needs to be ran to authenticate a user. Unless credentials expire or change, this command needs to be ran only once per user and system.

Setting credentials

To set credentials, run datalad osf-credentials anywhere on your system. This command prompts for user credentials and stores them in your system’s secure credential store for OSF operations.

# the default authentication method is token
$ datalad osf-credentials
You need to authenticate with 'https://osf.io' credentials. https://osf.io/settings/tokens provides information on how to gain access
token: <your token here>
You need to authenticate with 'https://osf.io' credentials. https://osf.io/settings/tokens provides information on how to gain access
token (repeat): <your token here>
osf_credentials(ok): [authenticated as <user> <e-mail>]

Two different methods of authentication are supported and can be set with the --method flag:

  • token: A personal access token. This is the recommended authentication type and default. Generate a personal access token under your user account at osf.io/settings/tokens. Make sure to create a full_write token to be able to create OSF projects and upload data to OSF!

  • userpassword: Your username and password combination from the OSF web interface.

# authenticate with user name and password
$ datalad osf-credentials --method userpassword
You need to authenticate with 'https://osf.io' credentials. https://osf.io/settings/account provides information on how to gain access
user: <your e-mail address>

password: <your password here>
password (repeat): <your password here>
osf_credentials(ok): [authenticated as <user name>]

The credentials are stored within a system’s encrypted keyring and DataLad retrieves them automatically for all future interactions with the OSF. Information on which user’s credentials are stored can be found by re-running datalad osf-credentials.

$ datalad osf-credentials
osf_credentials(ok): [authenticated as <user name> <e-mail>]

Environment variables

Alternatively, credentials can be set via environment variables: OSF_TOKEN, or both OSF_USERNAME and OSF_PASSWORD, as in

export OSF_TOKEN=YOUR_TOKEN_FROM_OSF

Resetting credentials

If credentials change they can be re-set using the --reset flag:

# token method is used by default, use --method userpassword for user + password credentials
$ datalad osf-credentials --reset
You need to authenticate with 'https://osf.io' credentials. https://osf.io/settings/tokens provides information on how to gain access
token: <your token here>
You need to authenticate with 'https://osf.io' credentials. https://osf.io/settings/tokens provides information on how to gain access
token (repeat): <your token here>
osf_credentials(ok): [authenticated as <user name> <e-mail>]

Invalid credentials

If you supply invalid credentials such as a mismatching user name and password combination or a wrong token, you will see the following error:

$ osf_credentials(error): None [Invalid credentials]

Please check for spelling mistakes, check your user name and password combination under your user account, or regenerate a token, and reset your credentials to fix this.