Skip to main content
Version: 8

Getting Started - Configure a Data Store

The bootstrap startup script (bootstrap-local-dms.ps1) creates a default data store and provisions the database schema automatically. This page covers the remaining step: creating API client credentials so you can authenticate and make requests.

What the Bootstrap Created​

Running bootstrap-local-dms.ps1 provisioned:

  • A data store (PostgreSQL or SQL Server database) registered in the Configuration Service
  • The Ed-Fi database schema provisioned via the api-schema-tools CLI

API client credentials are not created by the bootstrap unless you pass -AddSmokeTestCredentials. Otherwise, you create them separately so you control which vendor, claim set, and education organizations are associated with the client.

Step 1: Create API Credentials​

If you started the services with -AddSmokeTestCredentials, the bootstrap script created the credentials for you and printed the key and secret at the end of its output. Record them and continue with Step 2. The Configuration Service returns the secret only once, so it can't be retrieved later.

Otherwise, for local development, use the Get-SmokeTestCredential helper from the repository's smoke test module. It creates a vendor and application in the Configuration Service and returns a key and secret.

From the eng/docker-compose directory:

Import-Module ../smoke_test/modules/SmokeTest.psm1 -Force
$cred = Get-SmokeTestCredential -ConfigServiceUrl "http://localhost:8081"
Write-Host "Key: $($cred.Key)"
Write-Host "Secret: $($cred.Secret)"

Record the key and secret. You will need them to request API tokens.

info

Get-SmokeTestCredential creates a vendor named "Smoke Test Vendor" with an application using the EdFiSandbox claim set, pre-associated with a data store created by the bootstrap. It is intended for local development and testing, not production deployments.

Run it once per environment

Get-SmokeTestCredential creates a new application on each call. It does not retrieve existing credentials, and the generated secret cannot be recovered afterward. It reuses the "Smoke Test Vendor" vendor if it already exists, but the application name ("Smoke Test Application") must be unique for the vendor, so running it a second time against the same environment fails. To obtain a fresh credential, either pass a different -ApplicationName, or reset the local stack (./bootstrap-local-dms.ps1 -d -v, then re-run it without flags). The same applies if you started the services with -AddSmokeTestCredentials.

Multiple data stores

If you started with -AddSmokeTestCredentials, the bootstrap already associated its credential with every school-year data store, so you can skip this note.

If you created year-specific data stores (for example, with -SchoolYearRange), the default Get-SmokeTestCredential call above associates the client with only the first data store, so requests to the other school-year routes return a 403. Create a credential for all of the data stores instead. The snippet uses a different application name, so it works even if you already ran the call above:

# Get a Configuration Service admin token. This uses the local admin client
# that Get-SmokeTestCredential registers; Add-CmsClient reuses it if it exists.
Import-Module ../Dms-Management.psm1 -Force
Add-CmsClient -CmsUrl "http://localhost:8081" -ClientId "smoke-test-admin" -DisplayName "Smoke Test Administrator"
$adminToken = Get-CmsToken -CmsUrl "http://localhost:8081" -ClientId "smoke-test-admin"

# List the data stores and pass all of their IDs to the helper
$dataStores = @(Get-DataStore -CmsUrl "http://localhost:8081" -AccessToken $adminToken)
$dataStores | Select-Object id, name
$dataStoreIds = @($dataStores | ForEach-Object { [long]$_.id })
$cred = Get-SmokeTestCredential -ConfigServiceUrl "http://localhost:8081" `
-ApplicationName "Smoke Test Application (all data stores)" -DataStoreIds $dataStoreIds
Write-Host "Key: $($cred.Key)"
Write-Host "Secret: $($cred.Secret)"

The admin client's secret is a fixed development default in Dms-Management.psm1. Use these helpers only for local development.

Step 2: Request an OAuth Token​

Use the client credentials to obtain a bearer token from the Configuration Service:

$auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("<key>:<secret>"))
$token = Invoke-RestMethod -Method Post -Uri "http://localhost:8081/connect/token" `
-Headers @{ "Authorization" = "Basic $auth" } `
-ContentType "application/x-www-form-urlencoded" `
-Body @{
"grant_type" = "client_credentials"
}

A successful response returns a JSON object containing access_token, expires_in, and token_type.

info

If you are using Keycloak as your identity provider, the token endpoint is http://localhost:8045/realms/edfi/protocol/openid-connect/token. Keycloak also requires the realm and client to be configured before tokens will be accepted by the Ed-Fi API. See Identity Provider Configuration for the Keycloak token endpoint and setup instructions.

Step 3: Make an API Request​

Use the token to call the Ed-Fi API:

Invoke-RestMethod -Uri "http://localhost:8080/api/data/ed-fi/schools" `
-Headers @{ Authorization = "Bearer $($token.access_token)" }

An empty array [] is a valid response. It means the data store is connected and no schools have been loaded yet.

Troubleshooting

If you receive a 403 Authorization Denied response with the message "No database instances are authorized for this client," the credentials you are using were not linked to a data store when they were created. Ensure you are using the key and secret from -AddSmokeTestCredentials or Get-SmokeTestCredential, which associate the application with the data store created by the bootstrap. If you created a vendor or application manually through the Configuration Service, you must also associate it with a data store before API requests will succeed. If you have multiple data stores (for example, from -SchoolYearRange), see Multiple data stores above — the credential must be associated with every data store you intend to reach.

If you receive a 503 response with a message about database provisioning, run bootstrap-local-dms.ps1 again from a clean state (./bootstrap-local-dms.ps1 -d -v) — the data store exists but the schema was not provisioned.