API Access

FoundriesFactory APIs can be accessed with two different methods:

  1. OAuth2 tokens managed in the Application Credentials interface.
  2. API Tokens managed in the API tokens interface.

These credentials allow users to access:

  • REST APIs
    • Using the HTTP header OSF-TOKEN: <token>.
    • Using an OAuth2 bearer token Authorization: Bearer <access-token>
  • Git repositories. Access is granted by passing an API token as the password to Git clone and fetch operations.
  • Factory containers. Access is granted by passing an API token as the password to docker login hub.foundries.io.
  • Fioctl uses OAuth2 by default, but can also use API Tokens.

All tokens are created with scopes to help limit what they can do.

Note

Fioctl has a Docker Credential Helper which simplifies access to hub.foundries.io.

Common scopes

Some common scopes users may find handy include:

  • source:read-update - Useful for Git.
  • targets:read, devices:read, ci:read - read-only access for fioctl or REST API
  • targets:read-update, devices:read-update, ci:read - read-update access for fioctl.
  • containers:read - Useful for running docker commands on factory containers.

Token Scopes

Scopes define what resources a given token may perform operations on. The following scopes are supported:

source:read
Can perform git clone/fetch/pull operations.
source:read-update
Can perform git push operations.
source:delete
Can delete a reference (git push –delete …) and force-push (git push -f).
source:create
Can create a new references (tags and branches).
containers:read
Can docker pull.
containers:read-update
Can docker push.
ci:read
Can access CI builds https://api.foundries.io/projects/<factory>/lmp/.
ci:read-update
This isn’t needed normally because source:read-update triggers CI. However, certain custom use-cases that trigger CI builds via https://api.foundries.io/projects/<factory>/lmp/builds/ can use this.
devices:read
Can view device(s) https://api.foundries.io/ota/devices/.
devices:read-update
Can update configuration on a device https://api.foundries.io/ota/devices/<device>/config/
devices:create
Can create a device (lmp-device-register with an API token).
devices:delete
Can delete a device https://api.foundries.io/ota/devices/<device>/
targets:read
Can view targets.json https://api.foundries.io/ota/factories/<factory>/targets/.
targets:read-update
Can update targets.json https://api.foundries.io/ota/factories/<factory>/targets/.