Comments (11)
+1Β β
Sent from Mailbox
On Wed, Jun 18, 2014 at 3:41 AM, Rudolph Froger [email protected]
wrote:
I'm missing a paragraph on how authentication should be done. The paragraph on "Provide executable examples" mentions using a token with the comment "acquire from dashboard".
Thanks!
Reply to this email directly or view it on GitHub:
#25
from http-api-design.
Oops, obviously this is too tightly coupled to the Heroku case. I'll try to expand on it in the near future for you. Thanks for pointing this out as something that needs attention.
from http-api-design.
π as well. I really like the curl -is https://[email protected]/
example given, and I think a paragraph to explain that would be great.
from http-api-design.
In our case we have a couple ways it can be done. One is out-of-band (either from the website or via tools) and the other is via the API itself. In the API case we have a special login endpoint that you can call using your username and password (and you get a token back in return). Hopefully that clarifies at least a bit. The dashboard specific part here is certainly overly specific, but I'm not sure how best to generalize. Maybe if we just changed it from TOKEN
to CREDENTIALS
and noted that the means of acquiring this and format varies. I certainly think there is some advantage to a token in addition to user/pass though, so perhaps that at least is worth calling out. What do you all think?
from http-api-design.
Sounds good βΒ those are the cases I've encountered as well.
As for passing tokens, I've seen a few ways people tend to do it so far, and I'm not sure what's the best approach. It'd be nice to have guidelines on them.
- Pass it as a GET parameter, e.g.,
http://api.service.com/users?token=$TOKEN
- Pass it as a custom HTTP header, e.g.,
X-Auth-Token: $TOKEN
- Cookies?
- HTTP basic auth?
from http-api-design.
I lean somewhat towards basic auth for ease of use, as pretty much everything supports it. Plus you can technically pass it either with the host as above or in the headers if you really prefer. It also seems likely to do a good job of supporting both programatic and browser-based access (where other things may not do so as well). What do you think?
from http-api-design.
I'm all for basic auth β it's just what feels right. I don't know how to properly implement it though. Is it simply passing the token in the Authorization header, eg, Authorization: deadc0ffeebeef
?
from http-api-design.
@rstacruz sure. It depends. There are a couple ways you can use it (at least with most libraries/frameworks). The first is simply embedding it in the url, so stuff like https://USER:[email protected]
. A lot of clients and servers will just "do the right thing" with that. Under the covers, it can also be communicated more explicitly using the authorization header, though slightly different than your example, as Authorization: Basic BASE64(USER:PASS)
. Note that in both cases it has user/pass separated by a colon. If you just have a token, you can simply omit one. ie in the Heroku case we allow you to omit the username (so it becomes just :PASS
). Does that make it clearer?
from http-api-design.
Basic authentication is certainly the easiest but has the disadvantage of transferring the API key with every request. One might also consider other approaches like authenticate with the API key once per 'session' and then use a returned session id for subsequent requests (similar to how authentication for 'normal' users with web browsers works).
Another approach might be to use TOTP/HOTP/OCRA based authentication (the three OATH standards) so the API key is never included in the API requests.
TLS client certificate authentication could also be an option. This has the advantage that many HTTP client libraries already have support for client certificates.
When implementing something like session IDs or one of the OATH standards, one might want to supply a small 'curl' wrapper script to make it easier for developers to play with the API. Providing small implementation examples in various programming languages also helps the inexperienced developer.
from http-api-design.
@rudolphfroger those are definitely interesting options. I guess I haven't seen a lot of reason to prefer those somewhat more complicated options over basic auth. The exception is for cases like OTP where you want to provide a time-limited token. I think you can still pass that token around via basic though, for simplicity. Are there cases I'm not thinking about where more session based usage would be important? Beyond the insecurity of passing the token around each time, are there other concerns?
from http-api-design.
Security is my main concern with regards to authentication of API's. API's are made to easily retrieve large amounts of data and/or execute many powerful actions, most of the time much easier than via the web interface.
from http-api-design.
Related Issues (20)
- uuid in doubt HOT 4
- Dead link in about section HOT 1
- Guidance on implementing REST interfaces for state machine HOT 21
- I'm curious to know the reasoning for going with JSON Schemas instead of Swagger HOT 5
- How are you modeling authentication operation? HOT 1
- Using 409 Conflict for uniqueness checks HOT 2
- Create a website (Gitpage) HOT 3
- Traditional Chinese version, and add "List of Translations" HOT 5
- Consider adding language specific resources for implementing these principles HOT 1
- consider expanding error messaging as per white house guide HOT 7
- include more examples for main points HOT 9
- detail expansions
- Consider compatibility with jsonapi.org? HOT 8
- Why use UUID? HOT 12
- Paginating/ranging over non-unique fields HOT 15
- Pagination using Range cannot be consistent HOT 8
- Test Framework HOT 1
- The used time format is actually RFC5424, a subset of ISO8601 HOT 2
- Json with PLSQL ( PLJSON) HOT 1
- Links in README.md are 404 when viewed on Gitbook HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from http-api-design.