openapi: 3.2.0 info: title: V1 Lytics Auth API version: 1.0.0 description: "The Lytics API is a _restful_ *JSON* api that includes:\n* *Data Collection* api's for collection, and upload of custom data.\n* *Personalization api* for real-time user profile usage in personalization.\n* *Segmentation api* for lists of users, and creating/managing the segmentation rules.\n* *Catalog api* for schema information.\n* *Content api* for content recommendation, and content-classification to drive personalization.\n* *Management api* for general account management.\n## Authentication\nThe *Lytics API* supports authentication using one of the following:\nLogin to your account [Lytics App](https://activate.getlytics.com) and navigate to *Account* to find your keys.\nAfter you have acquired your token, use it to access the Lytics API.\nOur api supports two methods for authorization:\n* query string url parameter, using **access_token**\n* http **Authorization** HEADER\n\n```\n# example showing passing auth token in header\ncurl -XPOST 'https://api.lytics.io/api/segment' \\\n -H \"Authorization: pretendtoken8762\" \\\n -H 'Content-type: application/json' \\\n -d '{\"notreal\" : []}'\n\n# example as query string parameter\ncurl -XPOST 'https://api.lytics.io/api/segment?access_token=804ef78pretendtoken8762' \\\n -H 'Content-type: application/json' \\\n -d '{\"notreal\" : []}'\n\n```\n\nAdditionally, there are two types of authentication token's:\n\n* *User Auth Token* is normally just for the web admin. But may be used on the api, this is a user-specific token, and attributes actions to this user. This token expires.\n\n* *API User* is a less privileged role and does not expire. But, less history is available on actions.\n\n## IP Whitelisting\n\nFor better security, you can manage access to the Lytics API using the IP address whitelisting api_ip_whitelist setting on your account. This setting will also be applied to manage admin access to your Lytics account.\n\nProvide a CIDR value for the range of IP addresses you trust. Lytics will then ignore any unauthenticated users and/or IP addresses that fall out of the valid range. This means you can grant access to only your trusted users.\n\nWhat is CIDR?\nCIDR is a flexible allocation of IP addresses. Use an [IP address tool] (https://www.ipaddressguide.com/), to convert your IP addresses into a CIDR format, either v4 or v6.\n\n## Documentation Examples\n\nWe use [jq json command line prettifier](https://stedolan.github.io/jq/) in our examples throughout this doc.\n\n## Media Types\n\nOur API is a JSON REST API. We have data-upload api's which support\ncsv uploads as well.\n\nRequests with a message-body use plain JSON to set or update resource states.\n\n## Error States\n\nThe common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.\n\n## Query Parameters\n\nA variety of places our api accepts query parameters that allow a list of values.\nThe documentation will often say it allows `[]string or []int` (meaning an array of strings, or integers).\nWhen this occurs, we allow a variety of formats to pass these.\n\n* `ids=1234` convert this to []string{\"123\"}\n\n* `ids=[123,456]` convert this to []string{\"123\",\"456\"}\n\n* `ids=123,456` convert this to []string{\"123\",\"456\"}\n\n* `ids=123&ids=456` convert this to []string{\"123\",\"456\"}\n\n* `ids[]=123&ids[]=456` convert this to []string{\"123\",\"456\"} Note that we alias ids[] = ids" servers: - url: https://api.lytics.io tags: - name: Auth description: 'API for creation or storage of auth tokens. Most of these tokens are created from the Integrations/Imports setup for Lytics integrations. Additionally, api tokens can be created/managed from this endpoint. The oauth, config information are write only attributes that cannot be subsequently read from the api, and is stored encrypted.' paths: /api/auth/{id}: get: responses: '200': description: JSON representation of Auth Resource in addition to representing its state in the JSON. headers: {} content: application/json: schema: $ref: '#/components/schemas/AuthModel' examples: response: value: status: success data: account_id: 4f7b525bdba058fc096757a6 id: 1b53b88a06b418b07d601b6f57b8eb40 provider_id: 26cae7718c32180a7a0f8e19d6d40a59 provider_name: Facebook user_id: 4222fd7c8db7ebcb042e0547e3b4e128 security: - ApiKeyAuth: [] summary: Retrieve a Single Auth operationId: Retrieve a Single Auth description: 'This API is fairly special, as only the public portions of the auth model are returned, not all fields **config**, **oauth2token**, and **oathtoken** fields are never exposed.' tags: - Auth parameters: - name: account_id in: query description: Your Lytics account ID. required: false schema: type: string - name: id in: path description: ID of the Gist in the form of a hash. required: true schema: type: string - name: access_token in: query description: Lytics API access token. required: false schema: type: string post: responses: '201': description: JSON representation of Auth Resource in addition to representing its state in the JSON. headers: {} content: application/json: schema: $ref: '#/components/schemas/AuthModel' examples: response: value: status: success data: account_id: 4f7b525bdba058fc096757a6 id: 1b53b88a06b418b07d601b6f57b8eb40 provider_id: 26cae7718c32180a7a0f8e19d6d40a59 provider_name: Facebook user_id: 4222fd7c8db7ebcb042e0547e3b4e128 security: - ApiKeyAuth: [] summary: Create Auth operationId: Create Auth description: 'Create an auth, would normally never be used via the api, the web admin Integrations section manages these.' tags: - Auth parameters: - name: account_id in: query description: Your Lytics account ID. required: false schema: type: string - name: id in: path description: ID of the Gist in the form of a hash. required: true schema: type: string - name: access_token in: query description: Lytics API access token. required: false schema: type: string requestBody: content: application/json: schema: type: object properties: provider_id: type: string config: type: array items: type: object properties: name: type: string value: type: string example: provider_id: our_provider config: - name: apikey value: value_that_will_get_encrypted put: responses: '200': description: JSON representation of Auth Resource in addition to representing its state in the JSON. headers: {} content: application/json: schema: $ref: '#/components/schemas/AuthModel' examples: response: value: status: success data: account_id: 4f7b525bdba058fc096757a6 id: 1b53b88a06b418b07d601b6f57b8eb40 provider_id: 26cae7718c32180a7a0f8e19d6d40a59 provider_name: Facebook user_id: 4222fd7c8db7ebcb042e0547e3b4e128 security: - ApiKeyAuth: [] summary: Update Auth operationId: Update Auth description: '' tags: - Auth parameters: - name: account_id in: query description: Your Lytics account ID. required: false schema: type: string - name: id in: path description: ID of the Gist in the form of a hash. required: true schema: type: string - name: access_token in: query description: Lytics API access token. required: false schema: type: string delete: responses: '204': description: No Content headers: {} security: - ApiKeyAuth: [] summary: Remove an Auth operationId: Remove an Auth description: 'Deleting an auth is a very special operation. If any work is running (imports, exports), it will remove the auth from those works and stop them.' tags: - Auth parameters: - name: account_id in: query description: Your Lytics account ID. required: false schema: type: string - name: id in: path description: ID of the Gist in the form of a hash. required: true schema: type: string - name: access_token in: query description: Lytics API access token. required: false schema: type: string /api/auth/createtoken: post: responses: '201': description: Created headers: {} content: application/json: schema: $ref: '#/components/schemas/AuthApiTokenModel' examples: response: value: status: success data: account_id: 4f7b525bdba058fc096757a6 id: 1b53b88a06b418b07d601b6f57b8eb40 provider_id: 26cae7718c32180a7a0f8e19d6d40a59 name: my-token-for-service-x provider_name: Lytics config: - api_key: api_value security: - ApiKeyAuth: [] summary: Auth Create Token operationId: Auth Create Token description: Create Lytics api tokens. tags: - Auth parameters: - name: account_id in: query description: Your Lytics account ID. required: false schema: type: string requestBody: content: application/json: schema: type: object properties: expires: type: string scopes: type: array items: type: string name: type: string example: expires: 100h scopes: - admin - data name: my-token-for-serivce-x components: schemas: AuthModel: type: object properties: status: type: string data: type: object properties: account_id: type: string id: type: string provider_id: type: string provider_name: type: string user_id: type: string example: status: success data: account_id: 4f7b525bdba058fc096757a6 id: 1b53b88a06b418b07d601b6f57b8eb40 provider_id: 26cae7718c32180a7a0f8e19d6d40a59 provider_name: Facebook user_id: 4222fd7c8db7ebcb042e0547e3b4e128 AuthApiTokenModel: type: object properties: status: type: string data: type: object properties: account_id: type: string id: type: string provider_id: type: string name: type: string provider_name: type: string config: type: array items: type: object properties: api_key: type: string example: status: success data: account_id: 4f7b525bdba058fc096757a6 id: 1b53b88a06b418b07d601b6f57b8eb40 provider_id: 26cae7718c32180a7a0f8e19d6d40a59 name: my-token-for-service-x provider_name: Lytics config: - api_key: api_value securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey x-readme: explorer-enabled: true proxy-enabled: true