{"_id":"560ac5fef6994b0d0023bca6","project":"55db8f8f1a91690d007ad975","__v":16,"version":{"_id":"55db8f901a91690d007ad978","project":"55db8f8f1a91690d007ad975","__v":17,"createdAt":"2015-08-24T21:41:36.034Z","releaseDate":"2015-08-24T21:41:36.034Z","categories":["55db8f901a91690d007ad979","55db9856b3d6540d00886426","55dc751b00a8811900c230e3","55dc766255be9f21004ee250","55dc769200a8811900c230ed","55e4c701177b6e0d003330fa","55f4915caf0bc71900a53130","55f491b2be9c2b2100f0635d","560b22739c7be70d00100bd8","57488c53e8c6a420000b729c","574cefd95953e20e00f40f9f","5798edfd7700d30e00ad250c","579ac88234b5fd0e00b9e140","57c81c6d690c200e0047b72e","57d9b8fbda17c30e003897f1","57d9b90e608ea00e00f358d8","57d9b91cda17c30e003897f4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"55dde261746ace2b00dd6f73","parentDoc":null,"category":{"_id":"560b22739c7be70d00100bd8","pages":["560b229caf40a70d003df309","56bcb2cf9afb8b0d00d62df6"],"project":"55db8f8f1a91690d007ad975","version":"55db8f901a91690d007ad978","__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-29T23:44:51.456Z","from_sync":false,"order":6,"slug":"advanced-configurations","title":"Advanced configurations"},"githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-29T17:10:22.191Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"In most cases, the IMMUNIO agent will automatically instrument your app to detect all supported threat types.\n\nIf your app uses some features or libraries that Immunio does not yet support, you can still get full protection by calling the Immunio API from your app code to provide any missing information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Auth API\"\n}\n[/block]\nAll the auth APIs are accessed in the `immunio.api.auth` namespace. So to note a login event, you would do something like this:\n\n```python\nimport immunio.api.auth\nimmunio.api.auth.login_success(user_id=my_user.id, username=my_user.username)\n```\n\nThe Python Agent currently provides the following APIs:\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"set_current_user\"\n}\n[/block]\n```\nset_current_user(user_id=None, username=None, email=None)\n```\nInform Immunio of the current user for the current request. This function should be called for every request made to the App.\n\nThe `user_id` should be a unique un-changing reference for the user. Typically this should be a database primary key. If no id is available you can just pass the `username` value.\n\nThe `username` should be the human readable username for the account.\n\nThe `email` is optional, but can be used instead of a username for systems that require a valid email address as a username.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"login_success\"\n}\n[/block]\n```\nlogin_success(user_id=None, username=None, email=None)\n```\nInform Immunio of a successful login.  This function should be called during the request which actually logs in an existing user.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"login_failure\"\n}\n[/block]\n```\nlogin_failure(user_id=None, username=None, email=None, reason=None)\n```\nInform Immunio of a failed login attempt.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"password_reset_request_accepted\"\n}\n[/block]\n```\npassword_reset_request_accepted(user_id=None, username=None, email=None)\n```\nInform Immunio of a request to reset a user's password that was accepted by your system. Call this if someone requests a password reset and your system found a matching account and initiated the reset.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"password_reset_request_failed\"\n}\n[/block]\n```\npassword_reset_request_failed(search_value)\n```\nInform Immunio of a request to reset a user's password that did not match a known account.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"account_created\"\n}\n[/block]\n```\naccount_created(user_id=None, username=None, email=None)\n```\nInform Immunio of a newly created account.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Custom Event Reporting\"\n}\n[/block]\nThe IMMUNIO Agent allows custom business logic events to be reported to IMMUNIO. These custom events can be used to apply custom rate limiting thresholds on business logic events, or to trigger custom alerts on the IMMUNIO dashboard.\n\n```\nimmunio.api.extend.custom_event(event_name, metadata=None)\n```\n\nIt can be used like the following example:\n\n```\nimmunio.api.extend.custom_event(\"declined_creditcard_transaction\", {\n    \"transaction_id\": transaction.id,\n    \"transaction_value\": transaction.amount,\n    \"card_id\": hash(transaction.credit_card_number),\n}\n```\n\nWith a custom event like this, IMMUNIO can automatically limit the number of failed payment attempts from a given IP address or user account.\n\nThere are many other examples where custom events can be used to protect your site against many forms of abuse.","excerpt":"","slug":"python-agent-api","type":"basic","title":"Python Agent API"}
In most cases, the IMMUNIO agent will automatically instrument your app to detect all supported threat types. If your app uses some features or libraries that Immunio does not yet support, you can still get full protection by calling the Immunio API from your app code to provide any missing information. [block:api-header] { "type": "basic", "title": "Auth API" } [/block] All the auth APIs are accessed in the `immunio.api.auth` namespace. So to note a login event, you would do something like this: ```python import immunio.api.auth immunio.api.auth.login_success(user_id=my_user.id, username=my_user.username) ``` The Python Agent currently provides the following APIs: [block:api-header] { "type": "basic", "title": "set_current_user" } [/block] ``` set_current_user(user_id=None, username=None, email=None) ``` Inform Immunio of the current user for the current request. This function should be called for every request made to the App. The `user_id` should be a unique un-changing reference for the user. Typically this should be a database primary key. If no id is available you can just pass the `username` value. The `username` should be the human readable username for the account. The `email` is optional, but can be used instead of a username for systems that require a valid email address as a username. [block:api-header] { "type": "basic", "title": "login_success" } [/block] ``` login_success(user_id=None, username=None, email=None) ``` Inform Immunio of a successful login. This function should be called during the request which actually logs in an existing user. [block:api-header] { "type": "basic", "title": "login_failure" } [/block] ``` login_failure(user_id=None, username=None, email=None, reason=None) ``` Inform Immunio of a failed login attempt. [block:api-header] { "type": "basic", "title": "password_reset_request_accepted" } [/block] ``` password_reset_request_accepted(user_id=None, username=None, email=None) ``` Inform Immunio of a request to reset a user's password that was accepted by your system. Call this if someone requests a password reset and your system found a matching account and initiated the reset. [block:api-header] { "type": "basic", "title": "password_reset_request_failed" } [/block] ``` password_reset_request_failed(search_value) ``` Inform Immunio of a request to reset a user's password that did not match a known account. [block:api-header] { "type": "basic", "title": "account_created" } [/block] ``` account_created(user_id=None, username=None, email=None) ``` Inform Immunio of a newly created account. [block:api-header] { "type": "basic", "title": "Custom Event Reporting" } [/block] The IMMUNIO Agent allows custom business logic events to be reported to IMMUNIO. These custom events can be used to apply custom rate limiting thresholds on business logic events, or to trigger custom alerts on the IMMUNIO dashboard. ``` immunio.api.extend.custom_event(event_name, metadata=None) ``` It can be used like the following example: ``` immunio.api.extend.custom_event("declined_creditcard_transaction", { "transaction_id": transaction.id, "transaction_value": transaction.amount, "card_id": hash(transaction.credit_card_number), } ``` With a custom event like this, IMMUNIO can automatically limit the number of failed payment attempts from a given IP address or user account. There are many other examples where custom events can be used to protect your site against many forms of abuse.