Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      Concepts

      • Overview
      • Architecture
      • Features
      • Networking
      • Migrate to The Things Stack
      • Packet Broker
      • Server Addresses
      • Advanced Topics
        • Working with Users and Organizations
        • Adding OAuth Clients
        • Deleting, Restoring and Purging Entities
        • Metrics
        • Root Certificates
        • Telemetry
      • Troubleshooting
      • The Things Stack Sandbox

      Adding OAuth Clients

      Updated 13 February 2025 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      This section contains instructions for creating an OAuth Client.

      The Things Stack uses the OAuth 2.0 protocol for authentication and authorization.

      Considerations

      When you register an OAuth client, you should keep in mind that it will have to be approved by an administrator. The scope and duration of the review process depends on the network where you register your OAuth client. If you register in The Things Stack Cloud, Enterprise or Open Source, then the administrator (probably you) can approve it right away. If you register an OAuth client on The Things Stack Sandbox, the administrators will take some time to review if and how the OAuth client benefits the community.

      Guidelines for creation of OAuth clients on The Things Stack Sandbox

      When reviewing the requests of new OAuth clients, administrators always validate the following:

      • The ID and name of the user / organization that owns the OAuth client should clearly identify who is providing the service.
        • For public clients, this should typically be an organization with the brand name as ID.
        • For private/testing clients this can also be a user ID.
        • For personal testing clients, approval should not be needed.
        • IDs or names that could be confused with official TTN IDs/names will be rejected.
      • The ID of the OAuth client should ideally consist of the brand name of the application and the purpose of the OAuth client.
        • Example: “mycompany-gateway-onboarding”.
        • Keep in mind that you can’t change the Client ID after registration, and you can’t re-use the Client ID after deletion.
      • The name and description should be clear.
        • The name is typically the capitalized form of the ID.
          • Example: “MyBrand Gateway Manager”
        • The description should explain to users what the application does.
          • Example: “Manage your MyBrand gateway from the mobile app”
      • The redirect URI(s) should work.
      • The logout redirect URI(s) are optional.
      • The password grant should never be used. No exceptions.
      • The refresh_token grant should only be used when non-interactive access is clearly required.
      • The rights should be appropriate given the name and description of the OAuth client.

      Parameters Overview

      A few parameters listed below are usually used to describe an OAuth client.

      • The client ID uniquely identifies the OAuth client. Its restrictions are the same as for any other ID in The Things Stack.
      • The description is shown to the user when you request authorization.
      • The rights indicates what actions your OAuth client is allowed to perform. This is shown to the user when performing an authorization request. A full list of rights can also be found in the message reference.
      • The redirect URI is where the user is redirected after authorizing your OAuth client. At least one redirect URI must be configured while registering the OAuth client.
      • The client secret is issued when your OAuth client registration is accepted by a network administrator.
      • Console
      • CLI
      • HTTP (REST) API

      Adding OAuth clients using the Console

      To register an OAuth client using the Console, click the User settings dropdown in the left-hand sidebar and select OAuth clients. Then click + Add OAuth client in the top-right.

      OAuth client

      Enter the OAuth Client ID, Name and Description for your OAuth client. You can also add the Redirect URLs against which authorization requests will be checked, and Logout redirect URLs agains which client initiated requests are checked.

      Create an OAuth client

      Some Advanced administrator options are also available to set the state of the OAuth client, skip the authorization page or indicate endorsement.

      You can choose multiple Grant types, i.e. multiple OAuth flows that can be used for the client to obtain an OAuth token: Authorization code, Refresh token and Password.

      You also need to grant rights for your OAuth client. Keep in mind that, to provide the functionality of the application, a minimum set of rights has to be requested.

      Grant rights for an OAuth client

      Adding OAuth clients using the CLI

      To register an OAuth client using the CLI, use the following command:

      ttn-lw-cli clients create \
        --client-id <CLIENT-ID> \
        --name <CLIENT-NAME> \
        --description "My new OAuth client" \
        --redirect-uris <REDIRECT-URI> \
        --grants GRANT_AUTHORIZATION_CODE \
        --rights RIGHT_GATEWAY_ALL,RIGHT_ORGANIZATION_GATEWAYS_CREATE,RIGHT_ORGANIZATION_GATEWAYS_LIST,RIGHT_ORGANIZATION_INFO,RIGHT_USER_GATEWAYS_CREATE,RIGHT_USER_GATEWAYS_LIST,RIGHT_USER_INFO,RIGHT_USER_ORGANIZATIONS_LIST
      

      Adding OAuth clients using the HTTP (REST) API


      Endpoint Details
      Create OAuth client that belongs to an user.
      Item Value
      Endpoint /users/{collaborator.user_ids.user_id}/clients
      Request type POST

      Create OAuth client that belongs to an organization.
      Item Value
      Endpoint /organizations/{collaborator.organization_ids.organization_id}/clients
      Request type POST

      Example

      To create a client my-test-client on thethings.example.com, first create a JSON file named req.json in the same folder with the following example contents.

      {
        "client": {
          "ids": {
            "client_id": "my-test-client"
          },
          "name": "My Test OAuth",
          "description": "My Test OAuth description",
          "administrative_contact": {
            "user_ids": {
              "user_id": "testuser"
            }
          },
          "technical_contact": {
            "user_ids": {
              "user_id": "testuser"
            }
          },
          "redirect_uris": ["https://thethings.example.com"],
          "grants": ["GRANT_AUTHORIZATION_CODE"],
          "rights": [
            "RIGHT_GATEWAY_ALL",
            "RIGHT_ORGANIZATION_GATEWAYS_CREATE",
            "RIGHT_ORGANIZATION_GATEWAYS_LIST",
            "RIGHT_ORGANIZATION_INFO",
            "RIGHT_USER_GATEWAYS_CREATE",
            "RIGHT_USER_GATEWAYS_LIST",
            "RIGHT_USER_INFO",
            "RIGHT_USER_ORGANIZATIONS_LIST"
          ]
        },
        "collaborator": {
          "user_ids": {
            "user_id": "testuser"
          }
        }
      }
      

      The request using cURL is as follows.

      curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_KEY" \
      -d @./req.json \
       https://thethings.example.com/api/v3/users/testuser/clients
      
      {"ids":{"client_id":"my-test-client"},"created_at":"2024-09-16T17:52:30.975475Z","updated_at":"2024-09-16T17:52:30.975475Z","name":"My Test OAuth","description":"My Test OAuth description","administrative_contact":{"user_ids":{"user_id":"testuser"}},"technical_contact":{"user_ids":{"user_id":"testuser"}},"secret":"FG5K5HP64NVQUYCHKO4C5YLUZXCD6FAUCTI4HQQJZY7N75TTCT2A","redirect_uris":["https://thethings.example.com"],"grants":["GRANT_AUTHORIZATION_CODE"],"rights":["RIGHT_GATEWAY_ALL","RIGHT_ORGANIZATION_GATEWAYS_CREATE","RIGHT_ORGANIZATION_GATEWAYS_LIST","RIGHT_ORGANIZATION_INFO","RIGHT_USER_GATEWAYS_CREATE","RIGHT_USER_GATEWAYS_LIST","RIGHT_USER_INFO","RIGHT_USER_ORGANIZATIONS_LIST"]}
      

      Additional information

      For more details on how obtain access token from an approved OAuth client, consult the oauth access tokens section.

      ← User Management Deleting, Restoring and Purging Entities →

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories