bug: Social Connection Identity Linking API Inconsistency

[suin]

Describe the bug

The API endpoint for linking social identities shows inconsistencies between documentation and implementation:

1. Documentation specifies PATCH /api/my-account/identities
2. API returns Allow: POST header and 405 Method Not Allowed for PATCH
3. Using POST method results in 401 Unauthorized with verification_record.permission_denied

This makes it impossible to complete the social connection linking flow.

Expected behavior

Either:

• The API should accept PATCH method as documented, or
• POST method should work properly if that's the intended design

How to reproduce?

1. Request authorization URL:

POST /api/verifications/social
Authorization: Bearer <token>

{
  "connectorId": "github",
  "redirectUri": "http://localhost:3000/callback/github",
  "state": "asdfassdfafasd"
}

→ Returns 201 with verification record ID

2. Complete GitHub OAuth flow and receive callback code

3. Verify the social connection:

POST /api/verifications/social/verify
Authorization: Bearer <token>
{
  "connectorData": {
    "code": "<auth_code>",
    "state": "asdfassdfafasd"
  },
  "verificationRecordId": "<record_id>"
}

→ Returns 200 OK

4. Try to link identity with PATCH (as per documentation):

PATCH /api/my-account/identities
Authorization: Bearer <token>
logto-verification-id: <record_id>
{
  "newIdentifierVerificationRecordId": "<record_id>"
}

→ Returns 405 Method Not Allowed

5. Try with POST (as suggested by Allow header):

POST /api/my-account/identities
Authorization: Bearer <token>
logto-verification-id: <record_id>
{
  "newIdentifierVerificationRecordId": "<record_id>"
}

→ Returns 401 Unauthorized (verification_record.permission_denied)

Context

• Self-hosted, Logto version = v1.23.0
  • Container (Docker image)

[simeng-li]

Hi, thanks for the report. The sample code in the documentation is indeed misleading. Please use the POST method instead. We will update the documentation as soon as possible.

Regarding the 401 error you encountered in step 5, it’s likely that you are passing the wrong record_id in the logto-verification-id header.

Logto requires users to re-identify themselves before making any sensitive updates to their profile. Please refer to this section for more details.

The verificationRecordId you received in step 1 (and verified in step 3) represents the verification record for the new social identity to be linked to the user profile. This ID should be used as the newIdentifierVerificationRecordId in the request body for step 5.

As for the logto-verification-id header in step 5, it requires a separate user verification record, obtained through an existing verification method such as username/password or email verification code. Please follow the instructions I shared earlier. After successful identity verification, you will receive another verificationId, which must be included in the logto-verification-id header to indicate the user's verification status.

[suin]

@simeng-li

Thank you for the detailed follow-up! I managed to complete the social connection flow following your guidance about user re-authentication. However, I encountered another issue that's worth mentioning - the access token needs the "identities" scope.

Here's what happened:

POST /api/my-account/identities
Authorization: Bearer <token>
logto-verification-id: <user-verification-id>

{
  "newIdentifierVerificationRecordId": "<social-verification-id>"
}

Response: 400 Bad Request
{
  "message": "Unauthorized. Please check credentials and its scope.",
  "code": "auth.unauthorized"
}

Adding scopes=["identities"] when requesting the user token resolved this issue. While this might be obvious for those familiar with OpenID Connect, it would be helpful to mention this requirement in the documentation for developers who are new to these concepts.

The social connection flow involves several steps and can be quite complex. To help other Logto users, I'm planning to write a blog post with detailed steps and sample code.

Thanks again for the help and you can close this issue.

[suin]

I've published a detailed tutorial on implementing GitHub account linking with Logto in Next.js applications: https://github.com/suin/logto-next-connect-github/blob/main/doc/README.md

The tutorial covers:

• Complete implementation flow with code examples
• Error handling and troubleshooting
• Step-by-step guide with screenshots

I hope this helps other developers implementing social account linking with Logto!

I'm open to any feedback and happy to improve the content.

Also, would you be interested in having this content published on the Logto official blog? I'd be glad to refine the article based on your feedback to make it more helpful for the Logto community.

[wangsijie]

Thanks @suin, we'll update the documentation.