Create custom endpoint for Users

I’m trying to create a custom endpoint (/suggested-users) extending from users-permissions.
I tried a few things:

  • Create a User.js on the controller folder (extensions/users-permissions/controllers/Users.js) and then async suggested-users(ctx) => return 'Example',then I gave permissions to public and authenticated. (Error 500, error CastError: Cast to ObjectId failed for value “suggested-users” at path “_id” for model “user”)
  • Then I try to extend the routes files, with only /suggested-users, and later, with all the routes of the plugin + /suggested-users (But error Error creating endpoint get /suggested-users: handler not found "userspermissions.suggestedusers") (same error)
  • I try to create another controller, but trying to use the same route.js

I have been overriding some files from users-permission plugin, but never extend

Best workaround i found to have custom endpoints for users

Is create this directory structure

Route - /api/users/config/routes.js
Controller - /api/users/controller/users.js

And write your logic there
This allows you to have default controllers and your logic in separate files

Keep in mind, that first part of the handler is the Filename. You mentioned that you created a Users.js file with controller suggestedusers, but from routes you are accessing the userpermissions.js file, so it doesn’t contain your custom controller suggestedusers.

Look at the screenshot bellow:

To achieve your needs:
  1. Create the controller file /extensions/users-permissions/controllers/custom.js:
module.exports = {
  suggestedUsers: async (ctx, next) => {
    console.log('/suggested-users accessed.');
    await next();
  1. Create the route file extensions/users-permissions/config/routes.json:
  "routes": [
      "method": "GET",
      "path": "/suggested-users",
      "handler": "custom.suggestedUsers",
      "config": {
        "policies": []

  1. Make the route public or accessible only for authenticated.
  2. Profit:

this solution doesn’t works ?

(60) Strapi API Custom Controller || Profile/me POST - YouTube
This video will solve the problem

I did this exactly and the routes aren’t showing up in the role permissions config. When I try adding the route directly in the strapi-server.js file like this instead:

module.exports = (plugin) => {

    method: 'GET',
    path: '/users/suggested-users',
    handler: 'custom.suggestedUsers',

  return plugin

The server crashes with the following error:

[2022-10-20 10:27:26.136] error: Error creating endpoint GET /users/suggested-users: Cannot read properties of undefined (reading 'suggestedUsers')

For clarity, my custom.js file is located here: /extensions/users-permissions/controllers/custom.js

and looks like this (the same as yours)

module.exports = {
  suggestedUsers: async (ctx, next) => {
    console.log('/suggested-users accessed.');
    await next();

No it doesn’t, it solves a completely different problem. That video shows you how to make a custom endpoint for a custom content-type, not how to add a controller to a content-type that is included as part of a plugin

For any1 still looking into creating custom endpoint on this users-permissions plugin here is your answear:

Strapi does an awful job at documenting their changes…

Hi, i have tried this solutions but didn’t worked for me. Strapi version is 4.16.2.

Anyone has workaround ?

today I find out that custom controllers/services are heavily mentioned in documentation and people cannot actually use it.
this is very strange…