API Access

FoundriesFactory® APIs can be accessed via two 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 you may find useful include:

  • source:read-update: 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: 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

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

containers:read
Can docker pull.
containers:read-update
Can docker push.

CI

ci:read
Can access CI builds https://api.foundries.io/projects/<factory>/lmp/.
ci:read-update
This is not usually needed as source:read-update triggers the CI. However, custom use-cases that trigger CI builds via https://api.foundries.io/projects/<factory>/lmp/builds/ may use this.

Devices

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

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/.