I’m working on some demos for a tutorial I’m giving next month and since I’d like to show off Github’s API, I needed an access token for it. They have the usual web flow but I’m cutting as many corners as I can to keep the demos nice and quick, so I looked into the support Github has for generating an API key programmatically.

Creating the Token

You can log in with basic auth to generate the token (and then revoke the token later, which works for me as I’ll be demo-ing with it!). To do so, you make a POST request to the /authorizations endpoint:

curl -v -u lornajane -X POST https://api.github.com/authorizations --data @github.json

Let’s walk through each section from left to right. The -v is the verbose switch, so I see the headers as well as just the body response. This can be useful when debugging, and Github have all kinds of coolness in their headers, such as OAuth scope information and rate limits and things.

The -u is my basic auth username. You can put your password inline here but I don’t want to share it, so I won’t! If you don’t, you will be prompted to type your password, which then isn’t visible (again, since I’ll be demo-ing this, a good plan).

The -X sets which HTTP verb to use, since we’re creating a record, this is POST. And then the URL to POST to. Finally, I pass in some data. I’ve put the data in a file (see my earlier post about doing this) as it’s json and I prefer to contain it that way. The file contents are:

{"scopes":["gist","repo"]}

The response includes a field called “token” which is what you want to use for the next step. There is also some comprehensive github documentation on how to do this, showing which other fields can be used: http://developer.github.com/v3/oauth/#create-a-new-authorization (but I like tutorials better than docs, so I will refer to this example, then the docs, in future!)

Using the Token

I was creating gists as my example github demo (because they’re simple to work with), which is why you see the gist scope included above. To create a gist, I need to be logged in, but I can now just use my token, like this:

curl -v -H "Authorization: token 804ef78pretendtoken8762" -X POST https://api.github.com/users/lornajane/gists --data @github2.json

Let’s take another tour through – the verbose flag is there again (this is normal when I’m developing – and even when I demo I like to leave it in and point out anything of interest that goes past in the headers).

We send the token in the header with the -H switch, it’s an Authorization header – but look out for the token keyword as that is different on different systems and it tripped me up on this one.

Then we just proceed as before, POSTing some JSON data to the gists URL. Here’s the (trivially simple!) example I used:

{
  "description": "an API-created gist",
  "public": true,
  "files": {
    "file1.txt": {
      "content": "Some lovely code, how nice!"
    }
  }
}

When I go check my gists: there it is :)