There is not really any documentation of the API, we consider it largely an internal implementation detail for the UI until there is user demand for it because we don’t want to take attention away from all the native docker functionality that we integrate with. The UI is 100% static content on a CDN so it is entirely driven by the API. So there is quite a bit of tooling, framework, and design that goes into it… because we do expect user demand for it eventually, but more importantly because as the UI developer I’m the main consumer of it and insist on it 
. There is a lot of boring documentation about the specification of the API but it is all generic and not related to the specific Containers, Services, etc that the Rancher API implements.
If you haven’t already gone to the API & Keys section of the UI (under the user icon menu in the header) and clicked on the Endpoint, go ahead and do that. We call what you’re looking at the API UI; it lets you do almost anything with the API from a browser, and will show you the equivalent HTTP request or curl command. So if you click the registrationTokens link, then the Create button in the upper-right and “Show Request” it will show you those, then you can “Send Request” to do the actual create. This is all 100% static too, and driven by schemas in the API (/v1/schemas) that describe every field, every kind of resource, properties that tell you what things can be created or what actions are available on a specific instance of a resource, etc.
There is also a machine-generated CLI based on the same schemas (cattle-cli), and there will be a more friendly human-maintained version of that coming in the nearish future.
Important Note: If you click into the API from a browser you are authenticated as your user, which has access to all your Environments (and those are called projects in the API, because…reasons…). When you use the API keys offered in the UI, they are authenticated as that specific environment and have access only to it. So in the browser you want to be in /v1/projects/{id} to scope it to a particular environment for almost anything. With API keys you don’t need the /projects/{id} part because we already know what environment it is, so /v1/projects/1a5/registrationTokens in the user context is the same as /v1/registrationTokens in an environment API key context (though the other URL works too).
Registration Token is POST /v1/registrationTokens. Almost everything in the API is created asynchronously, including tokens, so this will give you back a token with state=registering and transitioning=yes. It will not contain the string you want yet. So you need to poll the links.self URL a little bit later until it becomes state=active (or subscribe to the WebSocket that will tell you when anything changes… this is how the UI works).
One the token is active it will have a registrationUrl property that’s the raw URL, and a command that is the full “sudo docker run …” string. You should use the command if possible because it includes the right agent version and the required flags, which may change from time to time.
The friendly CLI will have something like a --wait-for-it flag that will automatically do the waiting for the transition to finish stuff instead of you having to write code; cattle-cli does not currently have that.
If you’re going to use the API, be aware that we do not guarantee compatibility between versions yet. We generally are because it’s a pain for everyone to have to synchronize incompatible changes, but there will be things someday before a 1.0/GA release in some areas that will require changes (e.g. renaming projects and environments to match the UI terms). Watch rancher/rancher#1052 and rancher/rancher#384 in particular.