Skip to end of metadata
Go to start of metadata

API References

AndroidiOS

To view the method signatures, visit this link: http://phunware.github.io/maas-core-android-sdk/

To view the method signatures, visit this link: http://phunware.github.io/maas-core-ios-sdk/

 

 Architecture

Request/ Response Format

JSON is used for the request and response format. JSON is a lightweight and portable format that maintains human-readability.

When making POST or PUT requests, the request parameters MUST be JSON-encoded and placed in the request body. When making GET requests, the request parameters MUST be JSON-encoded, then URI-encoded and placed directly in the query string.

Clients should expect JSON-encoded responses for every request, even those that result in an error. The only exception is when uploading files using the S3 endpoints and the file is bigger than 2mb - you will receive a 413 error from Nginx.

HTTP Methods

Each method defines the HTTP method required depending on what the usage is. For example, if the method is used to simply get data, the HTTP method would be GET. If the method is used to delete data, it uses DELETE.

Date / Time Format

The date and time MUST be expressed in RFC 3339 format: YYYY-MM-DDThh:mm:ssZ

  • All times must be in the UTC time zone and indicated with a "Z". This is done to mitigate issues regarding Daylight Saving Time (DST).

  • No fractional seconds are allowed.

  • See section 5.6 of Date and Time on the Internet: Timestamps for more information.

Bracketed IDs ("[id]"s)

Whenever a bracketed ID ("[id]") appears in a method's name or URL (e.g. "GET /containers/[id]" or "https://cms-api.phunware.com/v2.0/containers/[id]"), treat it as a placeholder for the ID number of the item involved in the method (in this case, "GET /containers/58b72e03472f3f601810858f" or "http://cms-api.phunware.com/v1.0/containers/58b72e03472f3f601810858f").

Ellipses ("…"s)

Whenever an ellipsis ("…") appears in the JSON body, treat it as a placeholder for additional instances of the data that immediately precedes it.

PUT Methods & Partial Updates


There are a few differences in how the request parameters get handled by PUT methods:

  • There are no required parameters.

  • If a parameter IS NOT specified, it will retain its current value.

  • If a parameter IS specified, but with an empty value, then the value will be cleared.

  • If you pass in an identifier field for a container, schema, structure or content ID, it will be ignored.

GET Methods & Query Strings

The GET methods outlined in this document will use query strings, not JSON bodies, when making a request to a URL. This requires the user to convert JSON into a URL-encoded query string.

Example:

{ 
    "tags":  
    { 
        "any":  
        [ 
            "Zelda", 
            "Link" 
        ] 
    } 
}

Minified fragment using http://bigaqua.org/minify_json.html

{"tags":{"any":["Zelda","Link"]}}

URL-encoded, minified fragment using http://www.url-encode-decode.com/

%7B%3Ftags%3F%3A%7B%3Fany%3F%3A%5B%3FZelda%3F%2C%3FLink%3F%5D%7D%7D

URL-encoded, minified fragment as the query string.



In order to compose a request, a "?" is appended to the end of the request URL, then the URL-encoded, minified fragment is added.

 

http://cms-api.phunware.com/v1.0/schemas?%7B%3Ftags%3F%3A%7B%3Fany%3F%3A%5B%3FZelda%3F%2C%3FLink%3F%5D%7D%7D

Authorization

JWT Requirement

  • Authorization in CME API is handled using JSON Web Tokens (JWT), an industry standard for representing claims between two parties.

  • All endpoints require a valid, signed JWT issued from Phunware's LaaS system.
  • If no token is supplied, the API will respond with a 401 HTTP status code.

  • JWT expires in 24 hours

Setting the Header

In order to provide Phunware APIs with the JWT, you must provide a header named Authorization and the token must be prefixed with the word Bearer.

 

Key

Authorization

Value

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MTY3NCwiZW1haWwiOiJvcmdvd25lckBjeWJhZ2UuY29tIiwiZmlyc3RfbmFtZSI6IkN5YmFnZSIsImxhc3RfbmFtZSI6Ik9yZyBPd25lciIsIm9yZ3MiOltdLCJzZXNzaW9uX2lkIjoiNzk3ZWRjNmY2Mjk5Y2JmYmEyODE3NDlhMGFlZjI0YmNhNmZmODM0NSIsIm9yZ19pZCI6NTEsIm9yZ19uYW1lIjoiQ3liYWdlIENsZWFuIiwiaWF0IjoxNDg4MjI5ODY0LCJleHAiOjE0ODgzMTYyNjR9.Vd7BCYEkeWOq2B3_3Np9ylYDwYaAWyE1-e4ZvCIvK4E

Exceptions

The following endpoints do not require a JWT to be supplied.

  • GET /status

Response Handling

HTTP Status Codes

Success Payloads

Each successful response will include a JSON payload and the success code number.

200/201

Success

  • Used for general success.
  • Used when a POST operation results in the creation of a new resource (such that response should contain URI of newly created resource).

202

Accepted

Used when the clone process has been started successfully. The clone process will continue running in the background after the response is returned so it does not block the client.

Error Payloads

Each failed response will include a JSON payload that includes the error code number and message:

400

Bad Request

    • Used when one or more parameters are invalid.

    • Used when one or more required parameters are missing.

    • Used when the JSON payload is not valid JSON.

The actual message for this "Bad Request" error will vary depending on whether the error was caused by bad data sent in the request, a validation error when validating the request data or any other generic request error.


{
    "error": {
        "code": 400,
        "message": "Could not parse the request body."
    }
}

401

Unauthorized

Used when the operation fails authorization checks.

The actual message for this "Unauthorized" error will vary.


{
  "error": {
    "code": "UnauthorizedError",
    "message": "No authorization token was found"
  }
}

403

Forbidden

Used when the operation fails security checks (e.g. wrong app ID specified as input to retrieve specific data).

The actual message for this "Forbidden" error will vary.

 

{
  "error": {
        "code": 403,
        "message": "You are not allowed to delete this file."
    }
}

404

Not Found

Used when the requested resource does not exist (e.g. cloned container).

The actual message for this "Not Found" error will vary depending on what could not be found.

 

{
    "error": {
        "code": "server",
        "message": "File does not exist."
    }
}

423

Locked

Used when a clone process is in progress. Only one clone process can be started for a given organization.


The actual message for this error will vary. When attempting to clone a container that is already being cloned, for example, the following message would be returned:

 

{
    "error": {
        "code": "request",
        "message": "Cannot start clone process as there is an existing clone process already in progress for this container."
    }
}

500

Internal Server Error

    • Used when the (internal) server is down.

    • Used when a clone operation has failed.


The actual message for this "Internal Server Error" error will vary. For a failed container clone, for example, the following message would be returned:

 

{
    "error": {
        "code": "server",
        "message": "The clone process has failed: Error copying file in S3."
    },
    "data": {
        "orgId": <integer>,
        "name": <string>,
        "fromContainerId": <string>,
        "toContainerId": <string>,
        "type": <string>,
        "startedAt": <string>,
        "completedAt": <string>
    }
}

This document describes the specification for the security protocol implemented by various MaaS services. The security protocol includes information about request authentication as well as encryption/decryption of request and/or response data.

Definitions

Term

Definition

AES

Advanced Encryption Standard (AES) is the cipher used for encryption and decryption.

CBC

Cipher-block chaining (CBC) is a mode of operation whereby each block depends on the previous block.

Initialization Vector

The initialization vector is used by the block cipher to provide randomness to the output ciphertext.

Access Key

A unique key that identifies the client making the request. This key is used to get the additional keys used for request signing and encryption. To obtain this key, see Steps to Obtain Keys.

Signature Key

A unique key used to sign requests, check request authorization and check data integrity. To obtain this key, see Steps to Obtain Keys.

Encryption Key

A key used to encrypt and decrypt data exchanged between the client and the server. To obtain this key, contact your Phunware representative.

PKCS #7

This is a specification for padding the input data when using a block cipher so that the input length is divisible by the block size.

Steps to Obtain Keys

To obtain an application's access key or signature key, log into maas.phunware.com using the appropriate credentials. YOUR ACCOUNT will display: 

If you've been provisioned access to multiple organizations in the MaaS portal, click the grey "Switch" button at the upper left corner of the screen and type in the name of the application's containing organization:

The YOUR APPLICATIONS page will display. Click "Show Keys" beneath the application you'd like to get keys for. 

A panel like the below will display:

ON THIS PAGE

Core API Methods

Below are the methods in use with our Core API.

 

ORGANIZATION

To manage organizations, you must use a set of master API keys.

Organizations are the top-level containers for all data related to a particular customer.

{
    "id": <integer>,
    "name": <string>,
	"tapit_api_token": <string>,
	"tapit_signature_token": <string>,
	"is_active": <integer>,
    "created_at": <string>,
    "updated_at": <string>
}

Create an Organization

 

To manage organizations, you must use a set of master API keys.

This method is used to create a new organization.

Method

POST

URL

http://core-api.phunware.com/v1.0/organizations

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

name

string

The name of the organization. A unique string must be used to help differentiate this organization from other organizations.

tapit_api_token

string

The TapIt! Advertising API token.

tapit_signature_tokenstringThe TapIt! Advertising API signature token.

Request

{
    "data": 
	{
        "name": <string>,
	    "tapit_api_token": <string>,
	    "tapit_signature_token": <string>
    }
}

Example Request

POST the following request body to: http://core-api.phunware.com/v1.0/organizations

{
    "data": 
	{
        "name": "Hyrule, Inc."
    }
}

Response

A successful response will have a 200 status code and a body containing the details of the new organization:

{
	"data":
	{
		"id": <integer>,
		"name": <string>,
	    "tapit_api_token": <string>,
	    "tapit_signature_token": <string>,
	    "is_active": <integer>,
	    "created_at": <string>,
	    "updated_at": <string>
	}
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
	"data":
	{
		"id": "17",
		"name": "Hyrule, Inc.",
		"tapit_api_token": null,
		"tapit_signature_token": null,
		"is_active": 1,
		"created_at": "2015-01-01T12:00:00Z",
		"updated_at": "2015-01-01T12:00:00Z"
	}
} 

Retrieve an Organization

 

To manage organizations, you must use a set of master API keys.

This method is used to retrieve a specific organization.

Method

GET

URL

http://core-api.phunware.com/v1.0/organizations/[id]

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://core-api.phunware.com/v1.0/organizations/17

Response

A successful response will have a 200 status code and a body containing an object with organization data.

{
    "data": 
	{
	    "id": <integer>,
		"name": <string>,
	    "tapit_api_token": <string>,
	    "tapit_signature_token": <string>,
	    "is_active": <integer>,
	    "created_at": <string>,
	    "updated_at": <string>
    }
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
        "id": "17",
        "name": "Hyrule, Inc.",
		"tapit_api_token": null,
		"tapit_signature_token": null,
		"is_active": 1,
        "created_at": "1986-02-21T12:45:00Z",
        "updated_at": "2013-11-22T12:45:00Z"
    }
}

Retrieve a Collection of Organizations

 

To manage organizations, you must use a set of master API keys.

This method is used to retrieve an array of available organizations. You can optionally filter these based on the name.

Method

GET

URL

http://core-api.phunware.com/v1.0/organizations

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

name

string

A string containing the prefix or full name of the organization(s) you want to filter by.

Example Query Fragments

Search by name:

{
    "name": "Hyrule"
}

URL-encoded, minified fragment:

%7B%22name%22%3A%22Hyrule%22%7D

Example Request

Using "all" and "any" conditions together:

GET
http://core-api.phunware.com/v1.0/organizations?%7B%22name%22%3A%22Hyrule%22%7D

Response

A successful response will have a 200 status code and a body containing an array of organizations.

{
    "data": 
	[
        {
            "id": <string>,
            "name": <string>,
		    "tapit_api_token": <string>,
		    "tapit_signature_token": <string>,
		    "is_active": <integer>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
		{
            "id": <string>,
            "name": <string>,
		    "tapit_api_token": <string>,
		    "tapit_signature_token": <string>,
		    "is_active": <integer>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
        ...
    ],
	"pagination":
	{
		"results":
		{
			"from": <integer>,
			"to": <integer>,
			"total": <integer>
		},
		"pages":
		{
			"current": <integer>,
			"prev": <integer|null>,
			"next": <integer|null>,
			"total": <integer>
		}
	}
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
            "id": "17",
            "name": "Hyrule, Inc.",
		    "tapit_api_token": null,
		    "tapit_signature_token": null,
		    "is_active": 1,
            "created_at": "1986-02-21T12:45:00Z",
            "updated_at": "2013-11-22T12:45:00Z"
        },
        {
			"id": "2",
            "name": "Hyrule Engineering",
		    "tapit_api_token": null,
		    "tapit_signature_token": null,
		    "is_active": 1,
            "created_at": "1986-02-21T12:45:00Z",
            "updated_at": "2013-11-22T12:45:00Z"
        }
    ],
    "pagination":
	{
        "results":
        {
            "from": 1,
            "to": 2,
            "total": 2
        },
        "pages":
        {
            "current": 1,
            "prev": null,
            "next": null,
            "total": 1
        }
    }
}

Update an Organization

 

To manage organizations, you must use a set of master API keys.

This method is used to update an existing organization.

Method

PUT

URL

http://core-api.phunware.com/v1.0/organizations/[id]

Headers

X-Auth (see Security)

Request Parameters

See ARCHITECTURE > PUT Methods & Partial Updates.

Parameter

Value

Description

name

string

The name of the organization. A unique string must be used to help differentiate this organization from other organizations.

tapit_api_token

string

The API token to use when making calls to the TapIt! API.

tapit_signature_tokenstringThe API token to use when signing the request.
servicesarrayAn array of service IDs to associate with this organization.

Request

{
    "data": 
	{
        "name": <string>,
		"tapit_api_token": <string>,
		"tapit_signature_token": <string>,
		"services": <array>
    }
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/organizations/17

{
    "data": 
	{
        "name": "Hyrule Tower, Inc.",
		"services":
		[
			"analytics",
			"alerts",
			"content"
		]
    }
} 

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

Delete an Organization

 

To manage organizations, you must use a set of master API keys.

This method is used to delete a specific organization.

Method

DELETE

URL

http://core-api.phunware.com/v1.0/organizations/[id]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

DELETE
http://core-api.phunware.com/v1.0/organizations/17

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

CLIENT

 

 

Clients (a.k.a. applications) live within a particular organization and are used to separate data and permissions. Certain data, like analytics or alerts, live within the context of a client. Clients are also assigned a set of API keys that can be used to make calls to other Phunware APIs.

{
    "id": <integer>,
	"org_id": <integer>,
	"category_id": <integer>,
    "name": <string>,
	"type": <string>,
	"itunes_store_url": <string>,
	"android_play_url": <string>,
	"tapit_site_id": <integer>,
	"is_active": <integer>,
    "created_at": <string>,
    "updated_at": <string>
}

Create a Client

 

This method is used to create a new client.

Method

POST

URL

http://core-api.phunware.com/v1.0/clients

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

name

string

The name of the client. A unique string must be used to help differentiate this client from other clients.

org_id

integer

The ID of the organization to associate this client with.

category_idintegerThe ID of the category to associate this client with.
typestring

The client type. Possible values:

  • "ios"
  • "android"
itunes_store_urlstring

The full iTunes URL. Only valid when the "type" is "ios".

android_play_urlstringThe full Play store URL. Only valid when the "type" is "android".
tapit_site_idintegerThe ID of the associated TapIt! site.

Request

{
    "data": 
	{
        "name": <string>,
		"org_id": <integer>,
		"category_id": <integer>,
		"type": <string>,
		"itunes_store_url": <string>,
		"android_play_url": <string>,
		"tapit_site_id": <integer>
    }
}

Example Request

POST the following request body to: http://core-api.phunware.com/v1.0/clients

{
    "data": 
	{
        "name": "Hyrule App",
		"org_id": 100,
		"category_id": 200,
		"type": "ios",
		"itunes_store_url": "http://itunes.com/apps/hyrule",
		"tapit_site_id": 300
    }
}

Response

A successful response will have a 200 status code and a body containing the details of the new client:

{
	"data":
	{
		"id": <integer>,
        "name": <string>,
		"org_id": <integer>,
		"category_id": <integer>,
		"type": <string>,
		"itunes_store_url": <string>,
		"android_play_url": <string>,
		"tapit_site_id": <integer>,
		"is_active": <integer>,
		"created_at": <string>,
		"updated_at": <string>
	}
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
	"data":
	{
		"id": 100,
		"name": "Hyrule App",
		"org_id": 100,
		"category_id": 200,
		"type": "ios",
		"itunes_store_url": "http://itunes.com/apps/hyrule",
		"android_play_url": null,
		"tapit_site_id": 300,
		"is_active": 1,
		"created_at": "2015-01-01T12:00:00Z",
		"updated_at": "2015-01-01T12:00:00Z"
	}
} 

ON THIS PAGE

Retrieve a Client

 

This method is used to retrieve a specific client.

Method

GET

URL

http://core-api.phunware.com/v1.0/clients/[id]

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://core-api.phunware.com/v1.0/clients/100

Response

A successful response will have a 200 status code and a body containing an object with client data.

{
    "data": 
	{
	    "id": <integer>,
	    "org_id": <integer>,
	    "category_id": <integer>,
	    "name": <string>,
	    "type": <string>,
	    "itunes_store_url": <string>,
	    "android_play_url": <string>,
	    "tapit_site_id": <integer>,
	    "is_active": <integer>,
	    "created_at": <string>,
	    "updated_at": <string>
    }
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
        "id": 100,
        "name": "Hyrule App",
        "org_id": 100,
        "category_id": 200,
        "type": "ios",
        "itunes_store_url": "http://itunes.com/apps/hyrule",
        "android_play_url": null,
        "tapit_site_id": 300,
        "is_active": 1,
        "created_at": "2015-01-01T12:00:00Z",
        "updated_at": "2015-01-01T12:00:00Z"
    }
}

ON THIS PAGE

Retrieve a Collection of Clients

 

This method is used to retrieve an array of available clients. You can optionally filter these based on the name and/or ID.

Method

GET

URL

http://core-api.phunware.com/v1.0/clients

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

org_idinteger

The ID of the organization to get clients for.

This parameter is only used when the request is made using a set of master API keys.

name

string

A string containing the prefix or full name of the client(s) you want to filter by.

idarray | stringAn array of client IDs to return. This can also be set to a comma-delimited string of client IDs.

Example Query Fragments

Search by name:

{
    "name": "Hyrule"
}

URL-encoded, minified fragment:

%7B%22name%22%3A%22Hyrule%22%7D

Example Request

Using "all" and "any" conditions together:

GET
http://core-api.phunware.com/v1.0/clients?%7B%22name%22%3A%22Hyrule%22%7D

Response

A successful response will have a 200 status code and a body containing an array of clients.

{
    "data": 
	[
        {
		    "id": <integer>,
		    "org_id": <integer>,
		    "category_id": <integer>,
		    "name": <string>,
		    "type": <string>,
		    "itunes_store_url": <string>,
		    "android_play_url": <string>,
		    "tapit_site_id": <integer>,
		    "is_active": <integer>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
		{
		    "id": <integer>,
		    "org_id": <integer>,
		    "category_id": <integer>,
		    "name": <string>,
		    "type": <string>,
		    "itunes_store_url": <string>,
		    "android_play_url": <string>,
		    "tapit_site_id": <integer>,
		    "is_active": <integer>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
        ...
    ],
	"info":
	{
		"results":
		{
			"from": <integer>,
			"to": <integer>,
			"total": <integer>
		},
		"pages":
		{
			"current": <integer>,
			"prev": <integer|null>,
			"next": <integer|null>,
			"total": <integer>
		}
	}
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
	        "id": 100,
	        "name": "Hyrule App",
	        "org_id": 100,
	        "category_id": 200,
	        "type": "ios",
	        "itunes_store_url": "http://itunes.com/apps/hyrule",
	        "android_play_url": null,
	        "tapit_site_id": 300,
	        "is_active": 1,
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        },
        {
	        "id": 200,
	        "name": "Hyrule Castle App",
	        "org_id": 100,
	        "category_id": 200,
	        "type": "android",
	        "itunes_store_url": null,
	        "android_play_url": "http://play.google.com/store/apps/details?id=hyrulecastle",
	        "tapit_site_id": 300,
	        "is_active": 1,
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        }
    ],
	"info":
	{
		"results":
		{
			"from": 1,
			"to": 2,
			"total": 2
		},
		"pages":
		{
			"current": 1,
			"prev": null,
			"next": null,
			"total": 1
		}
	}
}

ON THIS PAGE

Update a Client

 

This method is used to update an existing client.

Method

PUT

URL

http://core-api.phunware.com/v1.0/clients/[id]

Headers

X-Auth (see Security)

Request Parameters

See PUT Methods & Partial Updates

Parameter

Value

Description

name

string

The name of the client. A unique string must be used to help differentiate this client from other clients.

org_id

integer

The ID of the organization to associate this client with.

category_idintegerThe ID of the category to associated this client with.
typestring

The client type. Possible values:

  • "ios"
  • "android"
itunes_store_urlstring

The full iTunes URL. Only valid when the "type" is "ios".

android_play_urlstringThe full Play store URL. Only valid when the "type" is "android".
tapit_site_idintegerThe ID of the associated TapIt! site.

Request

{
    "data": 
	{
        "name": <string>,
		"org_id": <integer>,
		"category_id": <integer>,
		"type": <string>,
		"itunes_store_url": <string>,
		"android_play_url": <string>,
		"tapit_site_id": <integer>
    }
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/clients/100

{
    "data": 
	{
        "name": "The Hyrule App",
		"org_id": 101,
		"category_id": 201,
		"itunes_store_url": "http://itunes.com/apps/thehyruleapp",
		"tapit_site_id": 301
    }
} 

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Delete a Client

 

This method is used to delete a specific client.

Method

DELETE

URL

http://core-api.phunware.com/v1.0/clients/[id]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

DELETE
http://core-api.phunware.com/v1.0/clients/100

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

CLIENT TYPE

 

A client type is associated with a client.

{
    "id": <integer>,
    "name": <string>,
	"key": <string>,
    "created_at": <string>,
    "updated_at": <string>
}

Retrieve a Collection of Client Types

 

This method is used to retrieve an array of available clients types.

Method

GET

URL

http://core-api.phunware.com/v1.0/client-types

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://core-api.phunware.com/v1.0/client-types 

Response

A successful response will have a 200 status code and a body containing an array of client types.

{
    "data": 
	[
        {
		    "id": <integer>,
		    "name": <string>,
		    "key": <string>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
		{
		    "id": <integer>,
		    "name": <string>,
		    "key": <string>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
        ...
    ]
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
	        "id": 100,
	        "name": "iOS",
	        "key": "ios",
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        },
        {
	        "id": 200,
	        "name": "Android",
	        "key": "android",
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        }
    ]
}

ON THIS PAGE

CLIENT CATEGORY

 

A client category is associated with a client.

{
    "id": <integer>,
    "name": <string>,
    "created_at": <string>,
    "updated_at": <string>
}

Retrieve a Collection of Client Categories

 

This method is used to retrieve an array of available client categories based on a given type.

Method

GET

URL

http://core-api.phunware.com/v1.0/client-categories

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

type_idinteger

The ID of the type to get categories for.

Example Query Fragments

Search by name:

{
    "type_id": 100
}

URL-encoded, minified fragment:

%7B%22type_id%22%3A100%7D

Example Request 

GET
http://core-api.phunware.com/v1.0/client-categories?%7B%22type_id%22%3A100%7D

Response

A successful response will have a 200 status code and a body containing an array of clients.

{
    "data": 
	[
        {
		    "id": <integer>,
		    "name": <string>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
		{
		    "id": <integer>,
		    "name": <string>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
        ...
    ]
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
	        "id": 100,
	        "name": "Entertainment",
			"type_id": 100,
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        },
        {
	        "id": 200,
	        "name": "Business",
	        "type_id": 200,
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        }
    ]
}

ON THIS PAGE

USER

 

Users are used to set permissions to a set of services. When users are associated with an organization, they are considered "organization users". If a user is not associated with a single organization, they are considered "global users". Global users are typically reserved for Phunware employees and contractors because they require more permissions than organization users.

{
    "id": <integer>,
	"org_id": <integer>,
    "role_id": <integer>,
    "google_id": <string>,
    "first_name": <string>,
    "last_name": <string>,
    "email": <string>,
    "time_zone": <string>,
	"is_active": <integer>,
    "created_at": <string>,
    "updated_at": <string>
}

Create a User

 

This method is used to create a new user.

Method

POST

URL

http://core-api.phunware.com/v1.0/users

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

emailstringThe user's email address.
first_namestringThe user's first name.
last_namestringThe user's last name

org_id

integer

The ID of the organization to associate this user with. If this is empty, then the user will be considered a "global user".

orgsarrayAn array of organization IDs to associate this user with. This parameter is only used when the "org_id" is empty, since only "global users" can be associated with more than a single organization.
clientsarrayAn array of client IDs to associate this user with.
role_idinteger

The ID of the role to associate this user with. If this is empty, then the user will be considered either an "Admin" if the "org_id" is also empty or an "Owner" if the "org_id" is not empty.

  • Admins can manipulate any data in the system.
  • Owners can manipulate any data within their organization.
google_idstringThe Google+ ID to associate this user with. Specifying a Google+ ID will allow this user to log in using their Google+ account.

time_zone

string

The user's time zone. Default: "UTC"

is_activeinteger

Specifies whether this user is active or not. Possible values:

  • 1: The user will be active.
  • 0: The user will not be active.

Request

{
    "data": 
	{
		"org_id": <integer>,
	    "role_id": <integer>,
	    "google_id": <string>,
	    "first_name": <string>,
	    "last_name": <string>,
	    "email": <string>,
	    "time_zone": <string>,
		"orgs": <array>,
		"clients": <array>,
		"is_active": <integer>
    }
}

Example Request

POST the following request body to: http://core-api.phunware.com/v1.0/clients

{
    "data": 
	{
		"org_id": 17,
	    "role_id": 200,
	    "google_id": "105330425913182640420",
	    "first_name": "Link",
	    "last_name": "Herooftime",
	    "email": "link@hyrule.com",
	    "time_zone": "America/Los_Angeles",
		"is_active": 1,
    }
}

Response

A successful response will have a 200 status code and a body containing the details of the new user:

{
	"data":
	{
		"id": <integer>,
		"org_id": <integer>,
	    "role_id": <integer>,
	    "google_id": <string>,
	    "first_name": <string>,
	    "last_name": <string>,
	    "email": <string>,
	    "time_zone": <string>,
		"is_active": <integer>
	    "created_at": <string>,
	    "updated_at": <string>
	}
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
	"data":
	{
		"id": 1986,
		"org_id": 17,
	    "role_id": 200,
	    "google_id": "105330425913182640420",
	    "first_name": "Link",
	    "last_name": "Herooftime",
	    "email": "link@hyrule.com",
	    "time_zone": "America/Los_Angeles",
		"is_active": 1,
		"created_at": "2015-01-01T12:00:00Z",
		"updated_at": "2015-01-01T12:00:00Z"
	}
} 

ON THIS PAGE

Retrieve a User

 

This method is used to retrieve a specific user.

Method

GET

URL

http://core-api.phunware.com/v1.0/users/[id]

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://core-api.phunware.com/v1.0/users/1986

Response

A successful response will have a 200 status code and a body containing an object with user data.

{
    "data": 
	{
		"id": <integer>,
		"org_id": <integer>,
	    "role_id": <integer>,
	    "google_id": <string>,
	    "first_name": <string>,
	    "last_name": <string>,
	    "email": <string>,
	    "time_zone": <string>,
		"is_active": <integer>
	    "created_at": <string>,
	    "updated_at": <string>
    }
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
		"id": 1986,
		"org_id": 17,
	    "role_id": 200,
	    "google_id": "105330425913182640420",
	    "first_name": "Link",
	    "last_name": "Herooftime",
	    "email": "link@hyrule.com",
	    "time_zone": "America/Los_Angeles",
		"is_active": 1,
        "created_at": "2015-01-01T12:00:00Z",
        "updated_at": "2015-01-01T12:00:00Z"
    }
}

ON THIS PAGE

Retrieve a Collection of Users

 

This method is used to retrieve an array of available users.

Method

GET

URL

http://core-api.phunware.com/v1.0/users

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

org_idinteger

The ID of the organization to get users for.

This parameter is only used when the request is made using a set of master API keys.

expand

array

An array of strings, where each string is the name of one of the associations for a user (e.g. "orgs"). You can also use dot-notation to drill into child associations (e.g. "clients.category").

Example Query Fragments

{
	"expand": [ "orgs", "clients.category" ]
}

URL-encoded, minified fragment:

%7B%22expand%22%3A%5B%22orgs%22%2C%22clients.category%22%5D%7D

Example Request

GET
http://core-api.phunware.com/v1.0/users?%7B%22expand%22%3A%5B%22orgs%22%2C%22clients.category%22%5D%7D

Response

A successful response will have a 200 status code and a body containing an array of users.

{
    "data": 
	[
        {
		    "id": <integer>,
			"org_id": <integer>,
		    "role_id": <integer>,
		    "google_id": <string>,
		    "first_name": <string>,
		    "last_name": <string>,
		    "email": <string>,
		    "time_zone": <string>,
			"is_active": <integer>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
		{
		    "id": <integer>,
			"org_id": <integer>,
		    "role_id": <integer>,
		    "google_id": <string>,
		    "first_name": <string>,
		    "last_name": <string>,
		    "email": <string>,
		    "time_zone": <string>,
			"is_active": <integer>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
        ...
    ],
    "info":
	{
        "results":
        {
            "from": <integer>,
            "to": <integer>,
            "total": <integer>
        },
        "pages":
        {
            "current": <integer>,
            "prev": <integer|null>,
            "next": <integer|null>,
            "total": <integer>
        }
    }
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
			"id": 1986,
			"org_id": 17,
		    "role_id": 200,
		    "google_id": "105330425913182640420",
		    "first_name": "Link",
		    "last_name": "Herooftime",
		    "email": "link@hyrule.com",
		    "time_zone": "America/Los_Angeles",
			"is_active": 1,
			"created_at": "2015-01-01T12:00:00Z",
			"updated_at": "2015-01-01T12:00:00Z"
        },
        {
			"id": 1987,
			"org_id": 17,
		    "role_id": null,
		    "google_id": null,
		    "first_name": "Princess",
		    "last_name": "Zelda",
		    "email": "zelda@hyrule.com",
		    "time_zone": "America/Chicago",
			"is_active": 1,
			"created_at": "2015-01-01T12:00:00Z",
			"updated_at": "2015-01-01T12:00:00Z"
        }
    ],
    "info":
	{
        "results":
        {
            "from": 1,
            "to": 2,
            "total": 2
        },
        "pages":
        {
            "current": 1,
            "prev": null,
            "next": null,
            "total": 1
        }
    }
}

ON THIS PAGE

Update a User

 

This method is used to update an existing client.

Method

PUT

URL

http://core-api.phunware.com/v1.0/users/[id]

Headers

X-Auth (see Security)

Request Parameters

See ARCHITECTURE > PUT Methods & Partial Updates.

Parameter

Value

Description

emailstringThe user's email address.
first_namestringThe user's first name.
last_namestringThe user's last name

org_id

integer

The ID of the organization to associate this user with. If this is empty, then the user will be considered a "global user".

orgsarrayAn array of organization IDs to associate this user with. This parameter is only used when the "org_id" is empty, since only "global users" can be associated with more than a single organization.
clientsarrayAn array of client IDs to associate this user with.
role_idinteger

The ID of the role to associate this user with. If this is empty, then the user will be considered either an "Admin" if the "org_id" is also empty or an "Owner" if the "org_id" is not empty.

  • Admins can manipulate any data in the system.
  • Owners can manipulate any data within their organization.
google_idstringThe Google+ ID to associate this user with. Specifying a Google+ ID will allow this user to log in using their Google+ account.

time_zone

string

The user's time zone. Default: "UTC"

is_activeinteger

Specifies whether this user is active or not. Possible values:

  • 1: The user will be active.
  • 0: The user will not be active.

Request

{
    "data": 
	{
		"org_id": <integer>,
	    "role_id": <integer>,
	    "google_id": <string>,
	    "first_name": <string>,
	    "last_name": <string>,
	    "email": <string>,
	    "time_zone": <string>,
		"orgs": <array>,
		"clients": <array>,
		"is_active": <integer>
    }
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/users/1987

{
    "data": 
	{
		"first_name": "The Princess",
	    "last_name": "Zelda, MD",
	    "email": "zeldaMD@hyrule.com",
	    "is_active": 0,
    }
} 

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Delete a User

 

This method is used to delete a specific user.

Method

DELETE

URL

http://core-api.phunware.com/v1.0/users/[id]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

GET
http://core-api.phunware.com/v1.0/users/1987

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Authenticate a User

 

This method is used to authenticate a user.

Method

GET

URL

http://core-api.phunware.com/v1.0/users/authenticate

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

providerstring

The authentication provider. Possible values:

  • "phunware": Authenticate using an email and password stored in the Phunware system.
  • "google": Authenticate using an OAuth token from Google.
emailstringThe user's email address. This parameter is only used when the provider is "phunware".

password

string

The user's password. This parameter is only used when the provider is "phunware".

access_tokenstringThe OAuth access token. This parameter is only used when the provider is "google".
expandarrayAn array of strings, where each string is the name of one of the associations for a user (e.g. "orgs"). You can also use dot-notation to drill into child associations (e.g. "clients.category").

Example Query Fragments

Authenticate using "phunware" provider:

{
	"provider": "phunware",
	"email": "link@phunware.com",
	"password": "insecure",
	"expand": [ "orgs", "clients.category" ]
}

URL-encoded, minified fragment:

%7B%22provider%22%3A%22phunware%22%2C%22email%22%3A%22link%40phunware.com%22%2C%22password%22%3A%22insecure%22%2C%22expand%22%3A%5B%22orgs%22%2C%22clients.category%22%5D%7D

Example Request

This example requires the query string data to be encrypted. See Encryption / Decryption for more details.

GET
http://core-api.phunware.com/v1.0/users/authenticate?<encrypted data>

Response

A successful response will have a 200 status code and a body containing an object with user and session data.

{
    "data": 
    {
	    "id": <integer>,
		"org_id": <integer>,
	    "role_id": <integer>,
	    "google_id": <string>,
	    "first_name": <string>,
	    "last_name": <string>,
	    "email": <string>,
	    "time_zone": <string>,
		"is_active": <integer>,
	    "created_at": <string>,
	    "updated_at": <string>
 
		// Example expansions:
		"orgs": <array>
		"clients": <array>
	},
	"session":
	{
		"id": <string>,
		"created_at": <string>,
		"expires_at": <string>
	}
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	{
		"id": 1986,
		"org_id": 17,
	    "role_id": 200,
	    "google_id": "105330425913182640420",
	    "first_name": "Link",
	    "last_name": "Herooftime",
	    "email": "link@hyrule.com",
	    "time_zone": "America/Los_Angeles",
		"is_active": 1,
		"created_at": "2015-01-01T12:00:00Z",
		"updated_at": "2015-01-01T12:00:00Z",
		"orgs":
		[
			{
		        "id": 17,
		        "name": "Hyrule, Inc.",
		        "tapit_api_token": null,
		        "tapit_signature_token": null,
		        "is_active": 1,
		        "created_at": "1986-02-21T12:45:00Z",
		        "updated_at": "2013-11-22T12:45:00Z"
			}
		],
		"clients":
		[
			{
		        "id": 100,
		        "name": "Hyrule App",
		        "org_id": 17,
		        "category_id": 200,
		        "type": "ios",
		        "itunes_store_url": "http://itunes.com/apps/hyrule",
		        "android_play_url": null,
		        "tapit_site_id": 300,
		        "is_active": 1,
		        "created_at": "2015-01-01T12:00:00Z",
		        "updated_at": "2015-01-01T12:00:00Z",
				"category":
				{
					"id": 200,
					"type_id": 300,
					"name": "Entertainment",
					"created_at": "2015-01-01T12:00:00Z",
					"updated_at": "2015-01-01T12:00:00Z"
				}
			}
		]
	},
	"session":
	{
		"id": "0001da4d19dad81154024517aeed16daca449b08",
		"created_at": "2015-01-01T12:00:00Z",
		"expires_at": "2015-01-01T14:00:00Z"
	}
}

ON THIS PAGE

Create User Account

 

This method is used to submit user details from a registration form. A confirmation email will be sent to the specified email address with a key that can be used when making a call to the email verification method.

Method

POST

URL

http://core-api.phunware.com/v1.0/users/register

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

userobject

An object container the user's information:

ParameterValueDescription
emailstring

The user's email address.

passwordstringThe user's password.
orgobject

An object containing the organization's information:

ParameterValueDescription
namestringThe organization's name.
email_urlstring

The URL that will be used in the email to link to the email confirmation page. The value should contain the string {key} somewhere that will be replaced with the actual verification key before the email is sent.

Example: "https://maas.phunware.com/verify-email/{key}"

Request

{
	"data":
	{
	    "user": 
		{
			"email": <string>,
			"password": <string>
    	},
		"org":
		{
			"name": <string>
		},
	} ,
	"email_url": <string>
}

Example Request

POST the following request body to: http://core-api.phunware.com/v1.0/clients

{
	"data":
	{
    	"user": 
		{
		    "email": "link@hyrule.com",
			"password": "insecure"
	    },
		"org":
		{
			"name": "Hyrule, Inc."
		},
	},
	"email_url": "https://maas.phunware.com/verify-email/{key}"
}

Response

A successful response will have a 200 status code and a body containing the details of the newly registered user and organization:

{
	"data":
	{
		"user": <object>,
		"org": <object>
	}
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
	"data":
	{
		"user":
		{
			"id": 1986,
			"org_id": 17,
		    "role_id": 200,
		    "google_id": "105330425913182640420",
		    "first_name": "Link",
		    "last_name": "Herooftime",
		    "email": "link@hyrule.com",
		    "time_zone": "America/Los_Angeles",
			"is_active": 1,
			"created_at": "2015-01-01T12:00:00Z",
			"updated_at": "2015-01-01T12:00:00Z"
		},
		"org":
		{
	        "id": "17",
	        "name": "Hyrule, Inc.",
	        "tapit_api_token": null,
	        "tapit_signature_token": null,
	        "is_active": 1,
	        "created_at": "1986-02-21T12:45:00Z",
	        "updated_at": "2013-11-22T12:45:00Z"
		}
	}
} 

ON THIS PAGE

Verify User Email

 

This method is used to verify the email address and activate the account. The key referenced in the URI is specified in the confirmation email after registering for an account.

Method

PUT

URL

http://core-api.phunware.com/v1.0/users/verify-email/[key]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

PUT
http://core-api.phunware.com/v1.0/users/verify-email/8fbfb0af04e65727198c05987a0f66991d74ff5a

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Change Password

 

This method is used to change the password associated with a user's account.

Method

PUT

URL

http://core-api.phunware.com/v1.0/users/[id]/change-password

Headers

X-Auth (see Security)

Request Parameters

See ARCHITECTURE > PUT Methods & Partial Updates.

Parameter

Value

Description

old_passwordstringThe user's old (existing) password.
new_passwordstringThe user's new password.

Request

{
	"old_password": <string>,
	"new_password": <string>
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/users/1986/change-password

{
	"old_password": "insecure",
	"new_password": "stillinsecure"
} 

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Request Reset Key

 

This method is used to request a password reset key that can be used to reset a user's password.

Method

PUT

URL

http://core-api.phunware.com/v1.0/users/reset-password

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

emailstringThe user's email address.
email_urlstring

The URL that will be used in the email to link to the reset password form. The value should contain the string {key} somewhere that will be replaced with the actual reset key before the email is sent.

Example: "https://maas.phunware.com/reset-password/{key}"

Request

{
	"email": <string>,
	"email_url": <string>
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/users/reset-password

{
    "email": "link@hyrule.com",
	"email_url": "https://maas.phunware.com/reset-password/{key}"
} 

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Submit New Password

 

This method is used to reset a user's password using a password reset key returned by requesting a reset key.

Method

PUT

URL

http://core-api.phunware.com/v1.0/users/reset-password/[key]

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

passwordstringThe user's new password.

Request

{
	"password": <string>
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/users/reset-password/8fbfb0af04e65727198c05987a0f66991d74ff5a

{
    "password": "newpassword"
} 

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

Validate Session ID

 

This method is used to validate a session ID that is returned from the user authentication method.

Method

GET

URL

http://core-api.phunware.com/v1.0/users/validate-session-id

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

idstring

A session ID returned by the user authentication method.

expandarrayAn array of strings, where each string is the name of one of the associations for a user (e.g. "orgs"). You can also use dot-notation to drill into child associations (e.g. "clients.category").

Example Query Fragments

{
	"id": "0001da4d19dad81154024517aeed16daca449b08",
	"expand": [ "orgs", "clients.category" ]
}

URL-encoded, minified fragment:

%7B%22id%22%3A%220001da4d19dad81154024517aeed16daca449b08%22%2C%22expand%22%3A%5B%22orgs%22%2C%22clients.category%22%5D%7D

Example Request

This example requires the query string data to be encrypted. See Encryption / Decryption for more details.

GET
http://core-api.phunware.com/v1.0/users/validate-session-id?<encrypted data>

Response

A successful response will have a 200 status code and a body containing an object with user data.

{
    "data": 
    {
	    "id": <integer>,
		"org_id": <integer>,
	    "role_id": <integer>,
	    "google_id": <string>,
	    "first_name": <string>,
	    "last_name": <string>,
	    "email": <string>,
	    "time_zone": <string>,
		"is_active": <integer>,
	    "created_at": <string>,
	    "updated_at": <string>
 
		// Example expansions:
		"orgs": <array[object]>
		"clients": <array[object]>
	}
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	{
		"id": 1986,
		"org_id": 17,
	    "role_id": 200,
	    "google_id": "105330425913182640420",
	    "first_name": "Link",
	    "last_name": "Herooftime",
	    "email": "link@hyrule.com",
	    "time_zone": "America/Los_Angeles",
		"is_active": 1,
		"created_at": "2015-01-01T12:00:00Z",
		"updated_at": "2015-01-01T12:00:00Z",
		"orgs":
		[
			{
		        "id": 17,
		        "name": "Hyrule, Inc.",
		        "tapit_api_token": null,
		        "tapit_signature_token": null,
		        "is_active": 1,
		        "created_at": "1986-02-21T12:45:00Z",
		        "updated_at": "2013-11-22T12:45:00Z"
			}
		],
		"clients":
		[
			{
		        "id": 100,
		        "name": "Hyrule App",
		        "org_id": 17,
		        "category_id": 200,
		        "type": "ios",
		        "itunes_store_url": "http://itunes.com/apps/hyrule",
		        "android_play_url": null,
		        "tapit_site_id": 300,
		        "is_active": 1,
		        "created_at": "2015-01-01T12:00:00Z",
		        "updated_at": "2015-01-01T12:00:00Z",
				"category":
				{
					"id": 200,
					"type_id": 300,
					"name": "Entertainment",
					"created_at": "2015-01-01T12:00:00Z",
					"updated_at": "2015-01-01T12:00:00Z"
				}
			}
		]
	}
}

ON THIS PAGE

USER ROLE

 

User roles manage a set of permissions that can be applied to a user.

{
    "id": <integer>,
	"org_id": <integer>,
    "name": <string>,
    "created_at": <string>,
    "updated_at": <string>
}

Create a User Role

 

This method is used to create a new user role.

Method

POST

URL

http://core-api.phunware.com/v1.0/user-roles

Headers

X-Auth (see Security)

Request Parameters

Required parameters are underlined.

Parameter

Value

Description

name

string

The name of the user role. A unique string must be used to help differentiate this user role from other user roles.

org_id

integer

The ID of the organization to associate this user role with.

This parameter is only used when a set of master API keys are used.

permissionsarrayAn array containing the string IDs of the permissions that will be allowed for this user role.

Request

{
    "data": 
	{
        "name": <string>,
		"org_id": <integer>,
		"permissions": <array>
    }
}

Example Request

POST the following request body to: http://core-api.phunware.com/v1.0/user-roles

{
    "data": 
	{
        "name": "Dev",
		"org_id": 17,
		"permissions":
		[
			"users.manage",
			"clients.manage",
			"alerts.configure"
		]
    }
}

Response

A successful response will have a 200 status code and a body containing the details of the new user role:

{
	"data":
	{
	    "id": <integer>,
	    "org_id": <integer>,
	    "name": <string>,
	    "created_at": <string>,
	    "updated_at": <string>
	}
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
	"data":
	{
	    "id": 6891,
	    "org_id": 17,
	    "name": "Dev",
	    "created_at": "2015-01-01T12:00:00Z",
	    "updated_at": "2015-01-01T12:00:00Z"
	}
} 

ON THIS PAGE

Retrieve a User Role

 

This method is used to retrieve a specific user role.

Method

GET

URL

http://core-api.phunware.com/v1.0/user-roles/[id]

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://core-api.phunware.com/v1.0/user-roles/6891 

Response

A successful response will have a 200 status code and a body containing an object with user role data.

{
    "data": 
	{
	    "id": <integer>,
	    "org_id": <integer>,
	    "name": <string>,
	    "created_at": <string>,
	    "updated_at": <string>
    }
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
	    "id": 6891,
	    "org_id": 17,
	    "name": "Dev",
        "created_at": "2015-01-01T12:00:00Z",
        "updated_at": "2015-01-01T12:00:00Z"
    }
}

ON THIS PAGE

Retrieve a Collection of User Roles

 

This method is used to retrieve a collection of available user roles.

Method

GET

URL

http://core-api.phunware.com/v1.0/user-roles

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

org_idinteger

The ID of the organization to get user roles for.

This parameter is only used when the request is made using a set of master API keys.

Example Request

GET
http://core-api.phunware.com/v1.0/user-roles

Response

A successful response will have a 200 status code and a body containing an array of user roles.

{
    "data": 
	[
        {
		    "id": <integer>,
		    "org_id": <integer>,
		    "name": <string>,
		    "created_at": <string>,
		    "updated_at": <string>
        },
        ...
    ],
	"info":
	{
		"results":
		{
			"from": <integer>,
			"to": <integer>,
			"total": <integer>
		},
		"pages":
		{
			"current": <integer>,
			"prev": <integer|null>,
			"next": <integer|null>,
			"total": <integer>
		}
	}
}

See Core API Response Handling for error payloads.

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
	        "id": 6891,
	        "name": "Dev",
			"org_id": 17,
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        },
        {
	        "id": 6892,
	        "name": "Sales",
	        "org_id": 17,
	        "created_at": "2015-01-01T12:00:00Z",
	        "updated_at": "2015-01-01T12:00:00Z"
        }
    ],
	"info":
	{
		"results":
		{
			"from": 1,
			"to": 2,
			"total": 2
		},
		"pages":
		{
			"current": 1,
			"prev": null,
			"next": null,
			"total": 1
		}
	}
}

ON THIS PAGE

Update a User Role

 

This method is used to update an existing user role.

Method

PUT

URL

http://core-api.phunware.com/v1.0/user-role/[id]

Headers

X-Auth (see Security)

Request Parameters

See ARCHITECTURE > PUT Methods & Partial Updates.

Parameter

Value

Description

name

string

The name of the user role. A unique string must be used to help differentiate this user role from other user roles.

org_id

integer

The ID of the organization to associate this user role with.

This parameter is only used when a set of master API keys are used.

permissionsarrayAn array containing the string IDs of the permissions that will be allowed for this user role.

Request

{
    "data": 
	{
        "name": <string>,
		"org_id": <integer>,
		"permissions": <array>
    }
}

Example Request

PUT the following request body to: http://core-api.phunware.com/v1.0/user-role/6891

{
    "data": 
	{
        "name": "Dev",
		"org_id": 17,
		"permissions":
		[
			"users.manage",
			"clients.manage",
			"alerts.configure"
		]
    }
} 

Response

A successful response will have a 200 status code and a body containing the details of the user role:

{
	"data":
	{
	    "id": <integer>,
	    "org_id": <integer>,
	    "name": <string>,
	    "created_at": <string>,
	    "updated_at": <string>
	}
} 

See Core API Response Handling for error payloads.

Example Response

Example body of successful response:

{
	"data":
	{
	    "id": 6891,
	    "org_id": 17,
	    "name": "Dev",
	    "created_at": "2015-01-01T12:00:00Z",
	    "updated_at": "2015-01-01T12:00:00Z"
	}
} 

ON THIS PAGE

Delete a User Role

 

This method is used to delete a specific user role.

Method

DELETE

URL

http://core-api.phunware.com/v1.0/user-roles/[id]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

DELETE
http://core-api.phunware.com/v1.0/user-roles/6891

Response

A success response will return a 200 status code with no data in the body of the response. See Core API Response Handling for error payloads.

ON THIS PAGE

  • No labels