GraphQL schema.

Endpoint

Smoke test

curl https://api.engineeringid.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { me { id email } }"
  }'

Authentication

Every request must carry a bearer token in the Authorization header — either a session cookie token (browser) or an API key (server-to-server).

Authorization: Bearer cred_live_a1b2c3d4...

• API keys are SHA-256 hashed before storage. The raw value is shown to you exactly once at creation time.
• Per-key scopes control which operations a key can perform — independent of user identity.
• Per-key rate limits isolate noisy integrations from each other.

Operations

The schema covers the full surface of the platform. Below are the most common operations developers reach for first. For an exhaustive list, query the introspection endpoint or open the schema browser.

Queries

Get the current user

query Me {
  me {
    id
    email
    name
    organizations {
      id
      name
      plan
    }
  }
}

List documents (paginated)

query Documents($first: Int!, $after: String) {
  documentsConnection(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        filename
        contentType
        size
        insertedAt
        sealedAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Variables

{
  "first": 25,
  "after": null
}

Verify a seal by code

Public — does not require authentication. Useful for embedding verification widgets in third-party sites.

query VerifySeal($code: String!) {
  verifySeal(code: $code) {
    valid
    verificationCode
    sealedAt
    document {
      filename
      version
      documentHash
    }
    credential {
      licenseNumber
      stateCode
      profession
      verificationMethod
    }
    sealedBy {
      name
    }
  }
}

Mutations

All mutations return a payload shaped { result, errors }. Validation errors are reported in errors[] with a field, message, and machine-readable code — top-level errors are reserved for transport / auth failures.

Seal a document

mutation CreateSeal($input: CreateSealInput!) {
  createSeal(input: $input) {
    seal {
      id
      verificationCode
      sealedAt
      document {
        id
        version
      }
    }
    errors {
      field
      message
      code
    }
  }
}

Variables

{
  "input": {
    "documentId": "01HXYZ-doc-uuid",
    "credentialId": "01HXYZ-cred-uuid"
  }
}

File uploads

File uploads use the GraphQL multipart request spec. Use any compliant client — apollo-upload-client, graphql-request, etc.

// Multipart request — see graphql-multipart-request-spec
// Uses a custom GraphQLUpload plug that extracts uploads into context.

mutation UploadDocument($file: Upload!, $folderId: ID) {
  createDocument(file: $file, folderId: $folderId) {
    document {
      id
      filename
      size
    }
    errors {
      field
      message
    }
  }
}

Subscriptions

Subscriptions stream over Phoenix Channels at wss://api.engineeringid.com/socket. Authenticate the same way as queries — pass the bearer token in the connect payload.

subscription BatchSealJobUpdates($jobId: ID!) {
  batchSealJobUpdated(jobId: $jobId) {
    id
    status
    total
    processed
    succeeded
    failed
  }
}

Pagination

All list queries follow the Relay connection spec: edges { cursor node } + pageInfo { hasNextPage endCursor }. Use first / after for forward paging, last/before for backward.

Errors

GraphQL responses always return HTTP 200 when the request was understood. Application errors live in the response body, not the status code.

{
  "errors": [
    {
      "message": "Document not found",
      "extensions": {
        "code": "NOT_FOUND",
        "field": "documentId"
      },
      "path": ["createSeal"]
    }
  ],
  "data": {
    "createSeal": null
  }
}

Error codes

Rate limits