Developers

Build With ArkID

ArkID is open identity infrastructure for research and innovation, and the developer platform behind its identifiers, relationships, resolver, and integrations is entering public preview.

If you are building systems that need durable identity, traceable relationships, and interoperable records across research and innovation workflows, ArkID is designed to be integrated, extended, and improved in the open.

Public Preview — core services are being hardened for public use. Documentation reflects current architecture and explicitly labeled roadmap items.

View GitHub Organisation Contact The Team

Current status

What Is Live, What Is in Preview, What Is Next

In flight

Core identity infrastructure

Relational data model

Resolver behavior

Documentation migration

Contributor onboarding

Public Preview focus

Identifier generation and validation

Public resolver

Core relationship model

Schema documentation

Early integration patterns

Next priorities

Expanded import pipelines

Hardened security and verification flows

Public repository consolidation

Additional federation and credential workflows

ArkID is being developed in public, but not every planned capability is production-ready. We separate current functionality from roadmap items throughout the developer experience.

What developers build with

Core Developer Surfaces

Identifier model

Work with standardized identifiers across the full research and innovation graph.

Relationship model

Model affiliations, authorship, participation, stewardship, funding, and other time-aware relationships.

Resolver

Resolve ArkIDs through public URLs and use stable entity references across systems.

APIs

Use REST and GraphQL interfaces to access entity data, relationships, and integrations.

Schemas

Build against documented entity schemas for users, organizations, projects, funding, ideas, and outputs.

Read API and Schema Docs Explore the Resolver

Integration guides

Integrate With ArkID Today

Four production surfaces, each with a concrete starting point.

Sign in with ArkID (OIDC)

Register a relying-party client (site admins: Admin → Clients & Keys), then run the standard authorization-code flow with PKCE. Every ID token carries the user’s ARKU claim.

# OIDC discovery
GET https://arkid.researchark.eu/arkid/auth/realms/arkid/.well-known/openid-configuration

# Authorization-code + PKCE (S256 enforced)
response_type=code&client_id=<your-client>&scope=openid profile email
# ID token claims include: sub, email, arku

Confidential clients receive a secret once at registration; rotate it any time from the admin console.

Resolve public identifiers

Every ARK identifier resolves to a public, owner-controlled JSON view — no authentication needed. Visibility flags and temporal validity windows are enforced server-side.

GET https://arkid.researchark.eu/api/public/{ARKU|ARKO|ARKP|ARKI|ARKD|ARKF}
GET https://arkid.researchark.eu/api/public/stats

# Example
curl https://arkid.researchark.eu/api/public/ARKO-3293-4784-9192-5569

Responses are cached for five minutes and invalidated on entity mutations.

Provision canonical projects & funding

Trusted services mint ARKP/ARKF identifiers idempotently: the same Idempotency-Key (or source binding) always returns the same canonical identifier, across retries and concurrency.

POST /api/projects   (Bearer user token; x-service-key for delegation)
Idempotency-Key: <stable-key>
{ "projectDetails": { "projectAcronym": "...", "fullProjectTitle": "..." },
  "fundingArkfs": ["ARKF-..."], "associatedPeople": [{ "arkidUser": "ARKU-...",
  "role": "Project Coordinator" }], "source": { "system": "...", "reference": "..." } }

Service keys are scoped (provisioning, dsar, arkpub, coi) and managed in Admin → Clients & Keys.

Verifiable credentials (OID4VCI)

Wallets obtain credentials through the pre-authorized-code flow with mandatory holder proof-of-possession; issued credentials are key-bound (cnf) and revocable.

GET  /api/vc/oid4vci/metadata            # issuer metadata
POST /api/vc/oid4vci/token               # pre-authorized code -> access token + c_nonce
POST /api/vc/oid4vci/credential          # { format, proof: { proof_type: "jwt", jwt } }
POST /api/vc/verify                      # verify any ArkID credential
GET  /api/vc/status/{externalId}         # revocation state

The proof JWT must carry your public JWK in its header and sign the current c_nonce for this issuer.

Architecture

ArkID Architecture at a Glance

ArkID is designed as modular, open infrastructure.

Core infrastructure

Keycloak-based identity foundations

Relational storage for identities and relationships

Public resolver services

Versioned schema and integration surfaces

Integration layer

REST and GraphQL APIs

External identifier integrations

ETL and import workflows

Resolver and public profile surfaces

Trust foundations

Standards-based identifier model

Federation and authentication support

Verifiable Credentials on the roadmap

Governance and sovereignty constraints

The architecture is designed to support institutional adoption without making ArkID dependent on one platform or one deployment model.

Quick start

Get Ready to Work With ArkID

Prerequisites

Docker and Docker Compose
For running Keycloak, PostgreSQL, and other services
Node.js and Bun
Preferred tooling for Next.js and monorepo workflows
TypeScript familiarity
Modern TypeScript-based service and frontend workflows throughout

High-Level Setup

git clone https://github.com/ArkID-by-ResearchArk/arkid.git
cd arkid
docker compose up -d
bun install
bun run dev:frontend

If the main organisation repositories are not yet public, use the current docs and contact channels to coordinate access, reference materials, or contribution pathways.

Go to GitHub Request Access

Project structure

Where Things Live

Backend

Configuration, middleware, routes, services, schemas, and identity logic.

Frontend

App routes, reusable components, utilities, and public-facing interfaces.

Identity and infrastructure

Keycloak configuration, deployment assets, service orchestration, and environment setup.

Documentation

Schemas, specifications, guides, and contribution materials.

The public documentation is your entry point. Repository structure becomes easier to navigate once you understand ArkID's entity model and relationship model.

Contributing