Shield

Client

You need to clients to do all oauth2 flows.
Clients are per service. So you need to have a service before creating a client.

WARNING

To create a client, you must be owner of the service.

Default Client scopes

When we create a service, Shield creates some default client scopes for you. If you needed to more client scopes, you should create them.

The default client scopes are as following:

  • openid
  • profile: To include profile data in the id_token and userinfo endpoint.
  • phone To include phone data in the id_token and userinfo endpoint.
  • email: To include email data in the id_token and userinfo endpoint.
  • address: To include address data in the id_token and userinfo endpoint.
  • roles: To include the user's roles in the id_token and userinfo endpoint.

You can update or delete the default client scopes as well.

Create a client

  • Make sure you're logged in and have a token to use in the next requests.
  • You should have service's id (get it from the administrator who creates the service for you)
  • Make sure you have your user id
  • If you want to provide any scope other than default Shield scopes, you need to create them before using in client creation request. In the client creation request, you can set scopes by using the scope's code.
  • Create a client (update token, owner_id, service_id, redirect_url and set other params to fit your needs) :
curl --location --request POST 'localhost:4000/api/v1/clients' \
--header 'Authorization: Bearer {auth_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my_first_client",
    "owner_id": "{your id}",
    "service_id":"{service id}",
    "redirect_uris": [
        "{your oauth2 redirection endpoint including http schema}"
    ],
    "allowed_grants": [
        "authorization_code",
        "password",
        "client_credentials",
        "refresh_token",
        "_implicit"
    ],
    "allowed_scopes": [

    ],
    "grants_config": {
        "authorization_code": {
            "code_expires_in": 3600000000000,
            "generate_refresh_token": true,
            "access_token_expires_in": 259200000000000,
            "refresh_token_expires_in": 1036800000000000,
            "force_pkce": false,
            "allowed_code_challenge_methods": null
        },
        "implicit": {
            "access_token_expires_in": 0
        },
        "password_credentials": {
            "generate_refresh_token": true,
            "access_token_expires_in": 259200000000000,
            "refresh_token_expires_in": 1036800000000000
        },
        "client_credentials": {
            "access_token_expires_in": 2592000000000000
        },
        "refresh_token": {
            "remove_old_access_and_refresh_tokens": true,
            "generate_new_refresh_token": true,
            "reset_refresh_token_expiry": true
        }
    }
}'

Check out the [create client](https://shield-api.vercel.app/#operation/clientsCreateParams) API info please.

Get a client secret

To get a client's secret, we need to send a request like following:

WARNING

When we return a client detail as response of GET client, it contains two id fields:

  • The id: The id field is the client's id in DB. You don't need to it most of the time.

  • The client_id: The client_id is the real clientID which you need in your requests. Use it when we need to the client_id in API calls.

curl --location --request POST 'localhost:4000/api/v1/clients/{client_id}/secret' \
--header 'Authorization: Bearer {token}'

Get a client token

Use your client_id which you got after creating a client to get a client token (please note client token and client secret are not the same things):

Tip

you can use query clients API if you don't have the client_id

INFO

Get your own token from login section to put it into this API call.

curl --location --request POST 'localhost:4000/api/v1/clients/{client_id}/token' \
--header 'Authorization: Bearer {token}'

Next Steps

Last Updated: