Economic Research Service Authentication

generated: '2026-09-06'
method: searched
source: >-
  https://www.ers.usda.gov/developer/data-apis/arms-data-api and
  https://api.data.gov/docs/developer-manual/ (API Key Usage), plus a live unauthenticated
  request to https://api.ers.usda.gov/data/arms/year on 2026-09-06 that returned HTTP 403
  API_KEY_MISSING, and https://gisportal.ers.usda.gov/server/rest/info?f=json.
provider: Economic Research Service
providerId: economic-research-service
description: >-
  Authentication profile for the two ERS API surfaces. Derived from documentation rather than
  from a securitySchemes block, because ERS publishes no OpenAPI. The two surfaces do not share
  an auth model: the ARMS Data API is key-gated through the shared Federal api.data.gov
  gateway, and the geospatial ArcGIS services are anonymous.
apis:
  - api: USDA ERS Data APIs
    aid: economic-research-service:ers-data-apis
    baseURL: https://api.ers.usda.gov/data
    auth_required: true
    schemes:
      - id: api_key_query
        type: apiKey
        in: query
        name: api_key
        primary: true
        description: >-
          The form ERS documents in every ARMS example, e.g.
          GET https://api.ers.usda.gov/data/arms/year?api_key=YOUR_API_KEY. api.data.gov notes
          the query parameter may be used for non-GET requests such as POST.
        source: https://www.ers.usda.gov/developer/data-apis/arms-data-api
      - id: api_key_header
        type: apiKey
        in: header
        name: X-Api-Key
        primary: false
        description: >-
          Platform-level alternative documented by api.data.gov for every API behind the
          gateway. Not shown in ERS's own examples, but accepted by the gateway that fronts
          api.ers.usda.gov.
        source: https://api.data.gov/docs/developer-manual/
      - id: http_basic_username
        type: http
        scheme: basic
        primary: false
        description: >-
          Platform-level alternative: the API key passed as the HTTP basic auth username with
          an empty password. Documented by api.data.gov, not by ERS.
        source: https://api.data.gov/docs/developer-manual/
    credential:
      issuer: api.data.gov
      signup: https://api.data.gov/signup/
      cost: free
      approval: automatic, delivered by email
      format: 40-character string
      scope: >-
        One key works across every agency API on api.data.gov, and the 1,000/hour limit is
        shared across all of them - the key is not scoped to ERS.
      rotation: not documented
      revocation: >-
        api.data.gov documents an API_KEY_DISABLED state administered by the platform; no
        self-service rotation or revocation flow is published.
    oauth2: false
    oidc: false
    mtls: false
    unauthenticated_response:
      status: 403
      body: '{"error":{"code":"API_KEY_MISSING","message":"No api_key was supplied. Get one at https://api.ers.usda.gov:443"}}'
      observed: '2026-09-06'
      note: >-
        Note that a missing credential returns 403, not 401, and carries no WWW-Authenticate
        header - an agent cannot discover the auth scheme from the challenge.
  - api: USDA ERS Geospatial APIs
    aid: economic-research-service:ers-geospatial-apis
    baseURL: https://gisportal.ers.usda.gov/server/rest/services
    auth_required: false
    schemes: []
    description: >-
      The published ArcGIS Server map, feature and image services answer anonymously over both
      REST (?f=json) and SOAP (?wsdl). ArcGIS Server reports isTokenBasedSecurity true at
      https://gisportal.ers.usda.gov/server/rest/info?f=json with a token endpoint at
      https://gisportal.ers.usda.gov/portal/sharing/rest/generateToken, but that governs the
      portal's own administrative and private content, not the public services ERS documents.
    token_service: https://gisportal.ers.usda.gov/portal/sharing/rest/generateToken
consent_identity:
  delegated_identity: false
  end_user_consent: not applicable
  note: >-
    There is no user-scoped identity anywhere in this surface. The api.data.gov key identifies a
    developer for rate-limiting and notification, not an end user, and no ERS API returns
    user-owned data.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com