CiviForm Docs
HomeAboutContactNewsFAQ
  • CiviForm Docs
  • Overview
    • What is CiviForm?
    • How does CiviForm work?
    • Glossary
  • User Manual
    • CiviForm Admin Guide
      • CiviForm Admin training overview
      • How to navigate CiviForm
      • Working with programs
        • Create a program
        • Edit a program
        • Show or hide questions based on inputs
        • Manage program eligibility
        • Manage address & service area validation
        • Manage notifications
        • How to publish programs
        • Set a pre-screener
      • Working with questions
        • Manage questions
        • Question export settings
        • Universal and Primary Applicant Information questions
        • Using enumerator questions & screens in a program
      • Manage translations for programs & questions
      • Manage versions for programs & questions
      • Working with applications
        • Add statuses to a program
        • Download exported data
      • Role management
        • Manage Program Admins
        • Manage Trusted Intermediaries
      • Manage API keys
      • Using Markdown
      • Migrating programs between environments
    • Program Admin Guide
      • How to become a Program Admin
      • Review completed applications
    • Trusted Intermediary Guide
      • Apply to a program
    • Onboarding Guide
      • Organization assessment
      • Program assessment
      • Getting started with service design
      • Journey mapping
      • Discovery, eligibility, and intake
      • Consolidating questions across programs
      • Working with existing tools and processes
      • Working across jurisdictions
      • Data reporting and other integrations
      • Security and privacy considerations
      • Staffing overview
  • IT Manual
    • Technical Deployment Guide
      • Initial Deployment
        • Terraform deploy system
          • AWS Terraform deployment
        • Authentication setup
        • Email configuration
        • GIS Service configuration
      • Upgrading to a New Release
        • CiviForm server environment variables
          • v1.20.0
          • v1.20.1
          • v1.21.0
          • v1.22.0
          • v1.23.0
          • v1.23.1
          • v1.24.0
          • v1.24.1
          • v1.24.2
          • v1.25.0
          • v1.26.0
          • v1.27.0
          • v1.28.0
          • v1.29.0
          • v1.30.0
          • v1.30.1
          • v1.31.0
          • v1.33.0
          • v1.34.0
          • v1.34.1
          • v1.34.2
          • v1.35.0
          • v1.36.0
          • v1.37.0
          • v1.38.0
          • v1.38.1
          • v1.38.2
          • v1.39.0
          • v1.40.0
          • v1.41.0
          • v1.42.0
          • v1.43.0
          • v1.44.0
          • v1.45.0
          • v1.46.0
          • v1.47.0
          • v1.48.0
          • v1.49.0
          • v1.50.0
          • v1.51.0
          • v1.52.0
          • v1.53.0
          • v1.54.0
          • v1.55.0
          • v1.56.0
          • v1.56.1
          • v1.57.0
          • v1.58.0
          • v1.59.0
          • v1.60.0
          • v1.61.0
          • v1.62.0
          • v1.63.0
          • v2.0.0
          • v2.0.1
          • v2.0.2
          • v2.1.0
          • v2.10.0
          • v2.11.0
          • v2.12.0
          • v2.13.0
          • v2.14.0
          • v2.15.0
          • v2.16.0
          • v2.17.0
          • v2.18.0
          • v2.19.0
          • v2.2.0
          • v2.20.0
          • v2.21.0
          • v2.22.0
          • v2.23.0
          • v2.24.0
          • v2.25.0
          • v2.26.0
          • v2.27.0
          • v2.28.0
          • v2.29.0
          • v2.3.0
          • v2.30.0
          • v2.31.0
          • v2.32.0
          • v2.33.0
          • v2.34.0
          • v2.35.0
          • v2.36.0
          • v2.37.0
          • v2.38.0
          • v2.39.0
          • v2.4.0
          • v2.4.1
          • v2.4.2
          • v2.4.3
          • v2.5.0
          • v2.6.0
          • v2.7.0
          • v2.8.0
          • v2.9.0
      • Monitoring
      • Troubleshooting Production
      • Disaster Recovery
      • Database Disaster Recovery
      • Production Database Access
    • Infrastructure Requirements
    • Existing deployments
    • API Integration
      • Authentication
      • List applications
    • Testing & QA
      • Testing resources
      • SQL queries to look for missing questions
  • Governance & Management
    • Project Management
      • On Call Guide
    • Governance
      • Roles, Committees, & Responsibilities
      • Governance Processes
      • Development Principles
      • Communication
Powered by GitBook
On this page
  • Authorizing the request
  • Using a username and password
  • Manually constructing the header
  • Additional security features
  • Obtaining API credentials
  • Testing API credentials

Was this helpful?

Edit on GitHub
Export as PDF
  1. IT Manual
  2. API Integration

Authentication

PreviousAPI IntegrationNextList applications

Last updated 6 months ago

Was this helpful?

All API requests must use HTTPS and authenticate by passing API key credentials using . Requests do this by setting the request header Authorization: Basic <credentials> where credentials is a secret token authenticating the request and associating it with a specific API key.

Authorizing the request

Depending on your API client, you may need to take different steps to construct the Authorization header.

Using a username and password

If your API client requires you to provide a username and password when using Basic Auth, use the Username and Password values provided on the API key confirmation screen. Your client will then create the Authorization header for you.

Example: Postman

Postman is an example of an API client that prompts for a username and password. The secret token isn't needed in this case and no other custom headers should be needed aside from the username and password.

Manually constructing the header

Some clients, such as curl, require constructing the header by hand. Use the API Secret Token value provided on the API confirmation screen, and construct a header that looks like Authorization: Basic <API Secret Token>.

Basic Auth requires that the request contain a header field in the form of Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of the Username and Password in the format username:password. CiviForm does this encoding for you and provides it in the value of API Secret Token.

Example: curl

For a curl, you'll use the following code, but replace the URL and replace the <api_secret_token> with the API secret token that is provided when API credentials are created.

curl https://staging.myciviform.gov/api/v1/checkAuth -vH "Authorization: Basic <api_secret_token>"

Additional security features

Obtaining API credentials

Testing API credentials

To test your API credentials, submit a GET request to /api/v1/checkAuth with your credentials.

With curl, that might look like this:

curl https://staging.myciviform.gov/api/v1/checkAuth -vH "Authorization: Basic <api_secret_token>"

If you recieve a 200 OK then your key is set up correctly to access CiviForm.

Additionally, API keys have several security features beyond simply checking the ID and secret of the key. If any of the constraints specified by those features are not met, API requests will receive a 401 response code. For more information see .

The CiviForm admin creates API keys using the admin UI. See for instructions on creating API keys and obtaining an API key's credentials.

managing API keys
HTTP Basic Auth
Api key security