# Authorization

- [Basic authentication](#basic-authentication) is required for workspaces management, and obtaining access token for operating against workspaces resources.
- [Token authentication](#token-authentication) is required when accessing workspace specific resources (Connection, Account, Extraction etc.)

## Basic authentication

Basic authentication is required for workspaces management, and obtaining access token for operating against workspaces resources.

*When Basic auth is required, use credentials provided by Improvado for Embedded API access.*

It is common implementation of Basic auth, as described in the [RFC 7616](https://datatracker.ietf.org/doc/html/rfc7617):

Credentials value is base64 encoded string composed from username and password separated by `:` .

Requests requiring this type of authentication must contain following header

`Authorization: 'Basic <credentials value>'`

Implementation example (Python):
```python
import requests

username = 'username@email.com'
password = 'password'

response = requests.get(
    'https://embedded.improvado.io/api/v3/workspaces',
    auth=requests.auth.HTTPBasicAuth(
        username=username,
        password=password,
    )
)
```

Authenticating with invalid credentials will return `401 Unauthorized`

## Token authentication

Token authentication is required when accessing workspace specific resources (Connection, Account, Extraction etc.)

Token value is obtained from [Create a token](/api/auth#create-a-token) endpoint.

Requests requiring this type of authentication must contain the following header:

`Authorization: 'Bearer <token value>'`

Token expiration time is 30 minutes.

The expiration time is renewed when the token is used to authorize a request.

New token acquisition is required if the token has expired.

Authenticating with an invalid or expired token will return `401 Unauthorized`

Implementation example (Python):
```python
import requests

username = 'username@email.com'
password = 'password'

# response {token: <token value>}
response = requests.post(
    'https://embedded.improvado.io/api/v3/token',
    auth=requests.auth.HTTPBasicAuth(
        username=username,
        password=password,
    ),
    json={'workspace_id': <int>}
)
token_value = response.json()['token']

auth_header = 'Authorization'
auth_value = 'Bearer {token_value}'.format(token_value=token_value)
headers = {auth_header: auth_value}

response = requests.get(
    'https://embedded.improvado.io/api/v3/datasources',
    headers=headers
)
```