tailscale / tailscale/tailscale

Misleading API Documentation Regarding Tailnet and Orgname Usage

Open
#8,239 0 comments 0 reactions 0 assignees View on GitHub
api bug L3 Some users P2 Aggravating T2 Visual Polish
Dominant language
Go
Stars
36.5k
Forks
3.2k
Avg merge
1d 23h
Merged PRs (30d)
132

Description

### What is the issue?

While using the Tailscale API, I encountered inconsistencies with how the terms "tailnet" and "orgname" are defined and applied. This has led to significant confusion and errors during implementation.

According to the current API documentation, one should use the "tailnet" identifier when making a call. For example, it suggests using the endpoint `GET /api/v2/tailnet/{tailnet}/acl`.

However, when implementing this as suggested, I consistently encountered errors. Through my troubleshooting process, I discovered that instead of using the "tailnet" as per the API documentation, it is the "orgname" that should be used in its place for the API call to work effectively. Consequently, the correct API call seems to be `GET /api/v2/tailnet/{orgname}/acl`.

In the Tailscale UI, the "tailnet" and "orgname" appear in different places and they are not the same. The "tailnet" is found within the settings and is presented as a URL, whereas the "orgname" is located at the top left corner of the UI and it's not the same as the "tailnet".

I believe this discrepancy in the documentation may pose challenges for users attempting to use the API effectively. It would be beneficial to clarify this in the API documentation to ensure accurate implementation in the future.

### Steps to reproduce

Follow the current documentation.

### Are there any recent changes that introduced the issue?

Not that I'm aware of.

### OS

Linux, macOS, Windows

### OS version

Latest

### Tailscale version

Latest

### Other software

N/A

### Bug report

_No response_

Contributor guide

Open the contributing guide

Research direction

Start by locating the API documentation for GET /api/v2/tailnet/{tailnet}/acl and review how “tailnet” and “orgname” are defined. Clarify which identifier the endpoint expects, update the example and terminology, and verify that the documented call matches the reported behavior.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.