Troubleshooting "An internal server error occurred": Create User Keys with the API

Overview

Unlike deploy keys, user keys are tied to a specific user, and thus can be used to checkout additional repositories. This can be useful for CI pipelines where you want to pull other repositories to do end-to-end testing, for example. Besides using our web UI, you can also create a user key for the project via our API.

Before You Start

Please ensure that you have authorized your account with GitHub before creating user keys.

This is necessary to allow CircleCI permission to create a user key associated with your GitHub user account.

You can find this page by visiting Project Settings > Checkout SSH Keys as shown in the screenshot below.


If you have not authorized with GitHub, you will encounter the following Internal Server Error message when creating a user key via API:

$ curl --request POST \
--url https://circleci.com/api/v2/project/gh/ORG_NAME/PROJECT_NAME/checkout-key \
--header "Circle-Token: $CIRLCLE_TOKEN" \
--header 'content-type: application/json' \
--data '{"type":"user-key"}'

{"message":"An internal server error occurred."}

To resolve this you can authorize CircleCI by performing a Re-Authentication using our guide linked here: https://support.circleci.com/hc/en-us/articles/360051228052-How-to-Perform-a-Re-Authentication

Once this has been done and you have authorized with GitHub you can add the user key.