# Add credentials

> Sign a data source in without writing a secret into a file. Bind each secret to the OS keychain, session memory, an environment variable, 1Password or an OAuth sign-in, and Folio sends it only to the address you confirmed.

Source: https://semvia.io/docs/federation/credentials

A connection defines where a source lives and how it signs in. It never holds the secret itself: workspace files are committed and shared, and Folio raises `secret/committed` on a password written into one. You bind each secret to a store on your machine, and Folio sends it only to the address the connection named when you bound it.

## Before you start

You need a source in your workspace, such as one from [Query a database](https://semvia.io/docs/federation/query-a-database), [Query a JSON API](https://semvia.io/docs/federation/query-a-json-api) or [Query CSV, Parquet and Excel files](https://semvia.io/docs/federation/query-data-files). This guide continues the connection Query a database names in `crm.ttl`, a [PostgreSQL](https://www.postgresql.org/) database that needs a username and a password. The steps are the same for the other sources.

## 1. Say how the source signs in

A connection points to the security scheme it signs in with through `td:hasSecurityConfiguration`, and a Postgres login is a Basic scheme. The first block of `crm.ttl` from Query a database already declares both, since `crm:db` points to `crm:dbLogin`, so the CRM database needs nothing added. For another source, add the same two parts: the `td:hasSecurityConfiguration` line on its connection and the scheme it points to.

Turtle

```turtle
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix rml:    <http://w3id.org/rml/> .
@prefix td:     <https://www.w3.org/2019/wot/td#> .
@prefix wotsec: <https://www.w3.org/2019/wot/security#> .
@prefix svdb:   <https://pkg.semvia.io/semvia/rml/connection#> .
@prefix crm:    <https://example.org/crm#> .

# Folio checks this file as an RML mapping.
<> dct:conformsTo <https://pkg.semvia.io/semvia/rml/profiles/rml-mapping> .

# The CRM database. svdb:driver names the ADBC driver that reads it.
# svdb:endpoint is its address, written the way Postgres writes it.
# Put in your own server's address.
# Drop sslmode=disable unless the database is on your own machine.
crm:db a svdb:AdbcConnection ;
  svdb:driver "postgresql" ;
  svdb:endpoint "postgresql://localhost:5432/postgres?sslmode=disable" ;
  td:hasSecurityConfiguration crm:dbLogin .

# The database takes a username and a password. You bind them in Folio, never here.
crm:dbLogin a wotsec:BasicSecurityScheme ;
  wotsec:in "auto" .
```

Graph

Figure: One card. db, an ADBC Connection, lists its driver postgresql and its endpoint postgresql://localhost:5432/postgres…, and has security configuration dbLogin.

The db connection signs in with the dbLogin scheme.

Folio requires TLS and checks the server's certificate.

A **Bind svwot:secretValue** and a **Bind svwot:username** lens appear above `crm:dbLogin`, and **Secrets** lists both fields under **Needs a credential**. Until both are bound, `crm:db` and `crm:dbLogin` carry error marks that read "A secret-marked field has no bound credential". A query that needs the database stops with "nothing is bound for this credential field" until both are bound.

## 2. Pick a store

Select a Bind lens. A panel opens under it with a choice of where the secret lives:

| Store | What Folio keeps | Use it when |
| --- | --- | --- |
| **Keychain** | The secret, in this machine's OS keychain | Your own machine. This is the default. |
| **Memory** | The secret, in the running engine only. It is gone when the engine restarts. | A shared or headless machine where nothing should be written to disk. |
| **Env var** | The variable's name. The value is read from the engine's environment each time. | CI, containers, or anywhere a secret manager already sets variables. |
| **Provider → 1Password** | A reference such as `op://Shared/CRM DB/password`. The [1Password CLI](https://developer.1password.com/docs/cli/get-started/), from [1Password](https://1password.com/), supplies the value. | 1Password already holds it. |
| **Provider → OAuth** | The authorization the provider hands back after you sign in, in the keychain. Access tokens live in memory only. | The provider offers sign-in instead of a password. |

Figure: crm.ttl in the Turtle Editor. Under the comment on the database's login are an Edit resource lens and the Bind svwot:secretValue and Bind svwot:username lenses, and a panel is open under them, above crm:dbLogin. Its Source row offers Keychain, Memory, Env var and Provider, with Keychain selected. Below, a Secret field reads Paste once, never shown again, with Bind and Cancel buttons and a link to Open in Secrets register. crm:dbLogin carries an error mark, since nothing is bound for it yet.

Binding the username. Keychain is selected by default.

Choose a source, fill in the field and select **Bind**. A pasted secret is never shown again. To change it, bind the field again.

## 3. Test it

Open **Secrets** in the activity bar, select a field, then **Test**. Folio connects with the bound secrets and reports one verdict, such as **Connection OK**, **Authentication failed** or **Host unreachable**, without showing the secret or the server's reply.

## Each secret is pinned to an address

When you bind a secret, Folio records the address it may be sent to:

- **A database** — Its whole address, database name and TLS mode included, and the driver that reads it.
- **A JSON API** — The origins of the forms in its [Thing Description](https://www.w3.org/TR/wot-thing-description11/).
- **CSV, Parquet or Excel files in a bucket** — The bucket, prefix and endpoint.

If an edit later moves the connection somewhere else, Folio stops sending the secret. To send it to the new address, open **Secrets** and confirm each field: select it, then **Test**. Test reports **Destination not confirmed**. Check the new address and select **Confirm destination**, or bind the field again.

## What each source asks for

| Source | Scheme | Fields to bind |
| --- | --- | --- |
| Postgres (`svdb:AdbcConnection`) | `wotsec:BasicSecurityScheme` with `wotsec:in "auto"` | `svwot:username`, `svwot:secretValue` |
| JSON API with a key (`td:Thing`) | `wotsec:APIKeySecurityScheme` with `wotsec:in` and `wotsec:name`, or `wotsec:BearerSecurityScheme` | `svwot:secretValue` |
| JSON API with sign-in (`td:Thing`) | `wotsec:OAuth2SecurityScheme` | Bind with **Provider → OAuth** |
| CSV, Parquet or Excel files in an [Amazon S3](https://aws.amazon.com/s3/) bucket (`svdb:BlobConnection`) | `svdb:SigV4SecurityScheme` | `svwot:username` (the access key ID), `svwot:secretValue` |
| CSV, Parquet or Excel files in [Azure Blob Storage](https://azure.microsoft.com/products/storage/blobs/) (`svdb:BlobConnection`) | `svdb:SharedKeySecurityScheme` | `svwot:secretValue` |

On a JSON API's Thing, declare the scheme with `td:definesSecurityScheme` and apply it with `td:hasSecurityConfiguration`.

CSV, Parquet and Excel files in the workspace or at a public URL need no scheme.

## Ask your agent to…

- Move the database connection in crm.ttl to db2.example.com, and tell me what I need to confirm in Folio.

[Next: Classes](https://semvia.io/docs/modeling/classes): Each construct a class schema supports: subclasses, fields, required values, datatypes, allowed values and defaults.
