How to find out the user key?

User mentions on Confluence pages are persisted as <ac:link><ri:user ri:userkey=\"{user key}\" /></ac:link>.

In my app I want to persist user mentions inside custom content objects and render user mentions in the static export view of my macros. In the future I may have the requirement to insert a user mention into a page.

The user picker component in my app use the /rest/api/search/user?cql=type=user%20and%20user.fullname~%22{name}%22 endpoint to find users to mention. This endpoint only returns the accountId, not the user key. I am not aware of any REST endpoint that returns the user key. How can I retrieve the user key of a user, or is there another way to persist a user mention?

1 Like

Does it help that the Atlassian Document Format version of the document uses Account IDs?

Thank you, I was not aware of that and it was a very helpful hint for finding a solution.

By experimenting with ADF, I found out that I can also persist user mentions as <ac:link><ri:user ri:account-id=\"{account ID}\" /></ac:link>, even though I don’t think this is documented anywhere, and also Confluence itself does not do it like this. This makes my requirement to retrieve the user key obsolete.

Should the need to retrieve the user key ever come up nonetheless, the convert body REST endpoint can be used. It seems to support the atlas_doc_format body type as well, even though the documentation does not mention that. Making a request like this will convert one or more user mentions from ADF to storage format. The user key(s) can then be extracted from the ri:userkey attributes.

const accountId = '...';
AP.request('/rest/api/contentbody/convert/storage', {
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        representation: 'atlas_doc_format',
        value: JSON.stringify({
            type: 'doc',
            content: [
                { type: 'mention', 'attrs': { id: accountId } }
    success: console.log,
    error: console.log

That representation key can also be used in the Get Content endpoint with ?expand=body.atlas_doc_format btw, if that helps.