Faros uses Credentials for source authentication. You can set up these credentials while adding a new source or through the Credentials page.

This page provides a centralized location to view and manage all your credentials, including information on their last modification.

Editing a credential automatically updates the authentication details for all sources linked to it.
Deleting a credential will cease data retrieval for any source using that credential.

Additionally, you have the flexibility to create multiple credentials for the same source, each with distinct permissions, allowing for tailored access control.

To set up a new credential, start by assigning a unique name and selecting the source type.

When you connect a specific source, you'll notice additional fields that may appear, as certain sources necessitate a particular set of permissions for Faros to successfully authenticate.

To determine the required permissions, place your cursor over the help icon located next to the credential (e.g., API key or token) input field.

For certain connections, Faros will verify the scope of your credentials. However, you have the option to bypass these verification checks by toggling Validate connection off.

Once your credentials are verified, for certain connections, you'll encounter additional prompts. For instance, with GitHub, you'll need to select or manually input the GitHub organizations you wish to sync data for.

Once you have created a credential, all future sources can use it to authenticate.

API token requirements

Faros uses API tokens to periodically pull metadata.

Define token expiration according to your company policy and automation.

Source	Token requirements
Asana	Provide a Personal Access Token. See the Asana documentation for instructions on creating the token.
Azure Boards	Provide access token with the following permissions: Work Items (Read), Graph (Read).
Azure Pipelines	Provide access token with the following permissions: Build (Read), Release (Read), Test Management (Read).
Azure Repos	Provide access token with the following permissions: Code (Read), Graph (Read).
BambooHR	Create an API key with a user that has an access level with 'View Only' permissions for the following fields on all employees: Basic Info -> First Name, Last Name; Address -> all fields; Contact -> Work Email; Hire Date; Job Information -> Job Title, Reporting to, Department
Bitbucket	VCS: Provide Bitbucket "App Password" with read permissions: Accounts: read, Pull Requests: read, Issues: read, Workspace membership: read, Projects: read, Repositories: read CICD: Provide Bitbucket "App Password" with read permissions: Pipelines: read, Repositories, read
Buildkite	Provide Buildkite API access token with the following read permissions: Organization Access, Read Organizations, Read Pipelines, Read Builds, GraphQL API Access
ClickUp	Provide a Personal API token. See the ClickUp documentation for instructions on creating the token.
CircleCI	Provide a Personal API token. See the CircleCI documentation for instructions on creating the token.
CodeDeploy	Provide valid AWS credentials with the following permissions: codedeploy:ListDeployments, codedeploy:BatchGetDeployments
Datadog	Provide an API token and Application key with scopes: `user_access_read`, `incident_read`, `slos_read`
Docker Registry	Provide a docker token with the scope read_api
GitHub	With classic tokens required scopes are: `repo`, `read:org`, `read:user` (for standard data) ...OR... `manage_billing:copilot`, `read:user` (for only Copilot data). For fetching Copilot data the token should belong to an organization owner. With fine-grained tokens required permissions are: (read-only in every case) `Repository` -> `Metadata`, `Contents`, `Pull Requests` and `Organization` -> `Administration`, `Members` (for standard data) ...OR... `Organization` -> `GitHub Copilot Business`, `Members` (for only Copilot data) APIs used for Copilot data are Copilot Metrics (organization and team metrics) and Copilot User Management (seat assignments list). Copilot Metrics API requires GitHub admins to enable access to it first at `Organization` -> `Settings` -> `Copilot` -> `Policies`
GitHub Enterprise	For organization and repository data, permissions are the same as GitHub. If using enterprise accounts for Copilot Business (i.e. enterprise without organizations), enterprise-version APIs will be used for Copilot data. Only classic tokens are supported. Required scopes: `read:enterprise` Copilot Metrics API requires GitHub admins to enable access to it first at `Enterprise` -> `Policies` -> `Copilot` -> `Policies`
GitLab, GitLab CE/EE	Provide GitLab personal access token with read permissions: read_api
Jira Cloud, Jira Server/DC	The integration user needs application access to Jira, the 'Browse Users' global permission, and the 'Browse Project' and 'View Development Tools' permissions for each project
Jenkins	Provide an API token. See the Jenkins documentation for instructions on creating the token
Opsgenie	Create an API key with "Read" and "Configuration access" rights. See the documentation
Octopus Deploy	Provide an Octopus Deploy API token. Octopus does not have permission scopes on their API tokens.
Okta	Provide an Okta token with scope `okta.users.read`
PagerDuty	Create a read-only API key by navigating to https://<your-org>.pagerduty.com/api_keys (instructions)
Phabricator	Create a Conduit API token with either a bot user or a regular user with visibility into the desired projects and repositories.
Sentry	Provide a Sentry token with scope org:read, project:read.
ServiceNow	Integration user should have the roles: sn_incident_read, cmdb_query_builder_read (details on roles)
SonarCloud	Create a user token with a user that has 'Browse' permissions for each project. See the documentation
SonarQube	Create a user token with a user that has 'Browse' permissions for each project. See the documentation
Other Credentials	Please reach out to [email protected] with questions.