API token authentication

[vncntprvst]

Hello,
I have a few questions / comments about token identification.
Currently, the documentation does not explain a lot about tokens. It is only mentioned in relation to Matlab's API tool:

When login with Python, the API asks for a username. But in fact, the user has to enter their email address.
This is explained in the docs, but could be clarified in the interface, as the user may not know that.

Once connected, the Python API returns a token.

I didn't see a way to get that token from the web API. I also didn't expect to get it from the Python API. Maybe I missed something, but I think this could be clarified in the documentation.
Once we have a token, what is the Python method to authenticate with it?

Peter, you mentioned in #7 that tokens do not expire. Is that still true?

Thanks!

[petersenpeter]

Hi Vincent

Good points - we intentionally tried to avoid having the user handle the actual token, but we will improve the tools and documentation. I am on vacation this week, but I will look into it when I return.

The tokens do not expire. You can get your token at https://www.brainstem.org/api/token/
But you need to access it using an API tool (post request) - not your browser.

Regarding the Python tool, handling of the token is built into the BrainstemClient: client = BrainstemClient(), but you can provide it as an input using above url.

@MingzeDou feel free to elaborate on the Python API tool if needed.

[MingzeDou]

Hi Vincent,

Thanks for your feedback on improving the documentation! I will add it to my to-do list.

We do have an updated tutorial in pull request. Many functions are shown there in detail. But it's still under discussion if this version is thorough enough.

In short, the way to use token is
token = "YOUR_SECRET_TOKEN"
client = BrainstemClient(token=token)

But it is recommended you save it somewhere safely and load it from a file. For example, you could have a config.json file:

{
"token": "YOUR_SECRET_TOKEN"
}

Then, you can load the token in Python like this:

import json

with open('config.json', 'r') as f:
config = json.load(f)
token = config['token']

client = BrainstemClient(token=token)

Please let us know if you have further questions or suggestions!

Thanks

[petersenpeter]

Hi Vincent

I updated the documentation on the token-based API authentication: https://support.brainstem.org/api/

As mentioned, this authentication is built into the API tools, but it should be clearer now.

And I agree, it would be better with tokens that expire, and we will work towards implementing this.

[petersenpeter]

Hi Vincent

We are changing the API tokens and are currently doing testing. There will be two types of tokens: Expiring tokens that can be requested with the API, and non-expiring tokens (1-year expiration) that can be created and deleted in the web interface. I think this is a more secure solution compared to what we currently have. Thanks for making the suggestion.

[petersenpeter]

Hi Vincent

We updated the API to allow for personal tokens that can be deleted. The API endpoints remain the same. You can learn more at: https://support.brainstem.org/api/

They will expire after one year but will automatically refresh upon use. There are also short-lived access tokens with refresh tokens that will expire in a month.

And here you can create/delete tokens: https://www.brainstem.org/private/users/tokens/

There is also a new import tool among other changes.

[vncntprvst]

Thanks Peter! Sounds good.