Implement API keys for client/repository authentication

[kaysiz]

Purpose

closes: Add github issue that originated this PR

Approach

Response payloads

Create API KEY

{
    "data": {
        "id": "31e3968c-7d8c-4b52-ae0f-345f2844cc85",
        "type": "apiKeys",
        "attributes": {
            "name": "Dataverse key",
            "keyPrefix": "DC.frSFkVLb",
            "created": "2026-06-23T12:37:16Z",
            "updated": "2026-06-23T12:37:16Z",
            "lastUsedAt": null,
            "revokedAt": null,
            "key": "DC.frSFkVLbXUY5hygoWay5R51cWvEMODw3"
        },
        "relationships": {
            "client": {
                "data": {
                    "id": "31467",
                    "type": "clients"
                }
            }
        }
    }
}

Get API Keys

{
    "data": [
        {
            "id": "31e3968c-7d8c-4b52-ae0f-345f2844cc85",
            "type": "apiKeys",
            "attributes": {
                "name": "Dataverse key",
                "keyPrefix": "DC.frSFkVLb",
                "created": "2026-06-23T12:37:16Z",
                "updated": "2026-06-23T12:37:16Z",
                "lastUsedAt": null,
                "revokedAt": null
            },
            "relationships": {
                "client": {
                    "data": {
                        "id": "31467",
                        "type": "clients"
                    }
                }
            }
        }
    ],
    "meta": {
        "total": 1
    }
}

Acceptance criteria

Creating an API key

• Users can retrieve an API key by 1) making a REST API request 2) with valid client credentials 3) via Basic username:password authentication 4) to retrieve an API key for a specific client 5) where the specific client corresponds to the authenticated client credentials.
  • Users must provide a name for the API key, which is saved.

MOCK CURLS

# Request with client credentials
curl -X POST https://api.datacite.org/credentials/api-keys \
     -u "datacite.datacite:password" \
     -d '{
       "data": {
         "type": "api-keys",
         "attributes": {
           "name": "Dataverse key"
         }
       }
     }'

Storing a created API key

• The API key string is only visible to the user when it is created and then is not visible again.
• The API key is stored hashed.
• When an API key is saved, it also receives an auto-generated uuid id and created date.

Accessing created API keys

• Users can request a list of a given client's API keys by authenticating with valid Basic client credentials corresponding to the target client.
  • The id, name, and created date for each API key must be serialized.
  • If valid credentials are not provided, then the REST API returns a 401.

MOCK CURLS

# Request with client credentials
curl -X GET https://api.datacite.org/credentials/api-keys \
     -u "datacite.datacite:password"

Using a created API key

• The API key can be used indefinitely.
• Users can send the API key via Basic authentication as the username.
  • When the API key is sent as the username, no password is required, and provided passwords are discarded.

Accepting API key credentials via Basic auth allows for continuity with existing authentication code and integrations.

• A request with the API key has the same permissions as an authenticated request with the Basic repository credentials used to create it.
  • Users can authenticate REST and MDS API requests using the API key.
• Users can continue to use Basic authentication with their client symbol username and password.
• Using the API key for authentication provides access to the Member API.
• Using the API key for authentication provides access to the Authenticated rate limit tier: https://support.datacite.org/docs/rate-limit
• Using the API key provides access to the monthly data file.
• Using the API key provides access to the Usage Reports API.

MOCKED CURLS

curl -X POST -H "Content-Type: application/vnd.api+json" --user dc_api_key: -d @doi.json https://api.datacite.org/dois 

curl -X PUT -H "Content-Type: application/vnd.api+json" --user dc_api_key: -d @doi.json https://api.datacite.org/dois/10.1234/1234

curl -H "Content-Type: application/xml;charset=UTF-8" -X PUT -i --user dc_api_key:-d @10.1234/1234.xml https://mds.datacite.org/metadata/10.1234/1234

Revoking a created API key

• The API key can be revoked by the user by id via REST API request with valid Basic client credentials corresponding to the target client.
  • When the API key is successfully revoked, it will no longer function as an authentication method.
  • When the API key is successfully revoked, it will no longer be serialized when accessing created API keys.

# Request with client credentials
curl -X DELETE https://api.datacite.org/credentials/api-keys/7623-x921-z882 \
     -u "datacite.datacite:password"

Open Questions and Pre-Merge TODOs

Learning

Types of changes

• Bug fix (non-breaking change which fixes an issue)

• New feature (non-breaking change which adds functionality)

• Breaking change (fix or feature that would cause existing functionality to change)

Reviewer, please remember our guidelines:

• Be humble in the language and feedback you give, ask don't tell.
• Consider using positive language as opposed to neutral when offering feedback. This is to avoid the negative bias that can occur with neutral language appearing negative.
• Offer suggestions on how to improve code e.g. simplification or expanding clarity.
• Ensure you give reasons for the changes you are proposing.