eContext Authentication API documentation¶

Introduction¶

The eContext Authentication API allows provides an application and user management platform allowing and allows authentication and (eventually) authorization controls that can be used to control access to various resources.

Input Format¶

The input format to the eContext Authentication API is specified using the HTTP Content-Type header (RFC 2616#section-14.17). A Content-Type of application/json is preferred, and there is no guarantee that other Content-Types will be honored.

Output Format¶

The output format is generally set by using the HTTP Accept header (RFC 2616#section-14.1). The default output format for the eContext API is JSON (application/json). As the default output format, all examples in this documentation are displayed using JSON.

The following output formats are currently supported:

application/json (RFC 4627)

Concepts¶

Applications¶

An Application is a concept which is used as the base resource against which Groups and Users are checked against. No Group or User may exist without a direct connection to an Application. An Application typically is comprised of an id, a name, and a description but may also contain Custom Data. When a User authenticates against the API the credentials are checked against the specified Application. Even if a username and password happen to be correct, if a User is not associated with the application specified in the authentication request, the request will fail.

The base Application inside the API is the “eContext Auth” Application which must be used in order to access the API.

Groups¶

A Group provides associations and Custom Data inside an Application. A particular group may belong to a single Application and may be associated with many Users.

Organizations¶

An Organization allows a structural hierarchy for storing Users. A User may not exist alone outside of an organization. An Organization may also contain custom-data that will then be associated with all of it’s users.

Users¶

A User is an account which may be used to authenticate against the API. A user may be associated with many Applications and many Groups but only with a single Organization. An authentication call against the API must include the specific Application which a client is seeking access to.

“Custom Data”¶

Additional data may be associated with Applications, Groups, and Users that may be used downstream by Applications. For example, an Application may look for certain attributes to be passed in with a User to override defaults, and those can be specified in the “Data” or “Custom Data” attributes of a User.

Authentication¶

The main purpose of the eContext Auth API is to allow a user to authenticate against an Application defined in the system.

POST /authenticate¶

Authenticate a user against an application resource.

Resource URL¶

https://auth.econtext.ai/api/authenticate

Parameters¶

Parameter	Type	Description
type	string	What type of authentication to perform. Currently it must be either `username` or `apikey`
application	string	The id of the application to authenticate to
credential	object	The username and password to authenticate with
credential.username	string	The username to authenticate with (or the apikey.id)
credential.password	string	The password to authenticate with (or the apikey.secret)

Return¶

The authenticate call typically returns a true or false value to indicate whether the credentials are valid.

Example Request¶

POST Request¶

curl -X POST  -u username:password \
  -H 'content-type: application/json' \
  -d '{
    "type": "username",
    "credential": {
      "username": USERNAME,
      "password": PASSWORD
    },
    "application": APP_ID
  }'
  https://auth.econtext.ai/api/authenticate

POST Response¶

{
  "econtext": {
    "result": {
      "authenticated": true
    },
    "elapsed": 0.0038661956787109375
  }
}

Applications¶

An application is a resource that can be authenticated against. A good example is the eContext Auth Application which is the the internal application that is used in order to connect to the eContext Auth API itself. Users who are associated with a particular application may authenticate against that application.

GET /applications¶

Retrieve a list of applications available in the system

Resource URL
Return
Example Request
- GET Request
- GET Response

eContext Authentication API documentation¶

Introduction¶

Input Format¶

Output Format¶

Concepts¶

Applications¶

Groups¶

Organizations¶

Users¶

“Custom Data”¶

Authentication¶

POST /authenticate¶

Resource URL¶

Parameters¶

Return¶

Example Request¶

POST Request¶

POST Response¶

Applications¶

GET /applications¶

POST /applications/application¶

GET /applications/application/{appid}¶

PUT /applications/application/{appid}¶

DELETE /applications/application/{appid}¶

GET /applications/application/{appid}/users¶

Groups¶

GET /groups¶

POST /groups/group¶

GET /groups/group/{groupid}¶

PUT /groups/group/{groupid}¶

DELETE /groups/group/{groupid}¶

GET /groups/group/{groupid}/users¶

Users¶

GET /users¶

GET /users/search/{search}¶

POST /users/user¶

GET /users/user/{userid}¶

PUT /users/user/{userid}¶

POST /users/user/{userid}/apikey¶

GET /users/user/{userid}/apikey/{apikeyid}¶

PUT /users/user/{userid}/apikey/{apikeyid}¶

DELETE /users/user/{userid}/apikey/{apikeyid}¶